From 0dc0ee4a721c81a8408309d793e4e678c915f971 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 25 Aug 2020 09:36:12 +0100 Subject: [PATCH] Add gtk-doc GTK_DOC_1_32-57-g3651bf3 from the gtk-doc-for-gtk4 branch --- gtk-doc-for-gtk4/AUTHORS | 3 + gtk-doc-for-gtk4/COPYING | 340 + gtk-doc-for-gtk4/COPYING-DOCS | 355 + gtk-doc-for-gtk4/ChangeLog | 5020 ++++++++++++ gtk-doc-for-gtk4/HACKING | 129 + gtk-doc-for-gtk4/MAINTAINERS | 22 + gtk-doc-for-gtk4/Makefile.am | 151 + gtk-doc-for-gtk4/NEWS | 1076 +++ gtk-doc-for-gtk4/README | 112 + gtk-doc-for-gtk4/TODO | 483 ++ gtk-doc-for-gtk4/autogen.sh | 19 + gtk-doc-for-gtk4/bugzilla.py | 161 + .../buildsystems/autotools/Makefile.am | 25 + .../buildsystems/autotools/gtk-doc.m4 | 113 + .../buildsystems/autotools/gtk-doc.make | 321 + .../autotools/gtk-doc.no-xslt.make | 309 + .../buildsystems/autotools/gtkdocize.in | 170 + .../buildsystems/autotools/meson.build | 41 + .../buildsystems/cmake/GtkDocConfig.cmake | 432 ++ .../cmake/GtkDocConfigVersion.cmake.in | 13 + .../cmake/GtkDocScanGObjWrapper.cmake | 68 + .../buildsystems/cmake/Makefile.am | 15 + .../buildsystems/cmake/meson.build | 26 + gtk-doc-for-gtk4/configure.ac | 221 + gtk-doc-for-gtk4/devhelp2.xsd | 217 + gtk-doc-for-gtk4/devhelp2.xsl | 173 + gtk-doc-for-gtk4/doc/README | 27 + gtk-doc-for-gtk4/doc/authors.txt | 151 + gtk-doc-for-gtk4/doc/design-1.x.txt | 28 + gtk-doc-for-gtk4/doc/design-2.x.txt | 173 + gtk-doc-for-gtk4/doc/gnome.txt | 84 + gtk-doc-for-gtk4/doc/gtkdoc.dot | 80 + gtk-doc-for-gtk4/doc/sections-file.txt | 66 + gtk-doc-for-gtk4/doc/setting-up.txt | 86 + gtk-doc-for-gtk4/doc/style-guide.txt | 234 + gtk-doc-for-gtk4/examples/Makefile.am | 111 + gtk-doc-for-gtk4/examples/README | 9 + gtk-doc-for-gtk4/git.mk | 333 + gtk-doc-for-gtk4/gtk-doc-fo.xsl | 35 + gtk-doc-for-gtk4/gtk-doc.doap | 39 + gtk-doc-for-gtk4/gtk-doc.pc.in | 7 + gtk-doc-for-gtk4/gtk-doc.xsl | 836 ++ gtk-doc-for-gtk4/gtkdoc-check.in | 41 + gtk-doc-for-gtk4/gtkdoc-depscan.in | 404 + gtk-doc-for-gtk4/gtkdoc-fixxref.in | 61 + gtk-doc-for-gtk4/gtkdoc-mkdb.in | 65 + gtk-doc-for-gtk4/gtkdoc-mkhtml.in | 55 + gtk-doc-for-gtk4/gtkdoc-mkhtml2.in | 58 + gtk-doc-for-gtk4/gtkdoc-mkman.in | 53 + gtk-doc-for-gtk4/gtkdoc-mkpdf.in | 52 + gtk-doc-for-gtk4/gtkdoc-rebase.in | 60 + gtk-doc-for-gtk4/gtkdoc-scan.in | 63 + gtk-doc-for-gtk4/gtkdoc-scangobj.in | 81 + gtk-doc-for-gtk4/gtkdoc/__init__.py | 0 gtk-doc-for-gtk4/gtkdoc/check.py | 150 + gtk-doc-for-gtk4/gtkdoc/common.py | 582 ++ gtk-doc-for-gtk4/gtkdoc/config.py | 28 + gtk-doc-for-gtk4/gtkdoc/config_data.py.in | 14 + gtk-doc-for-gtk4/gtkdoc/fixxref.py | 405 + gtk-doc-for-gtk4/gtkdoc/highlight.py | 51 + gtk-doc-for-gtk4/gtkdoc/md_to_db.py | 758 ++ gtk-doc-for-gtk4/gtkdoc/meson.build | 45 + gtk-doc-for-gtk4/gtkdoc/mkdb.py | 4947 ++++++++++++ gtk-doc-for-gtk4/gtkdoc/mkhtml.py | 90 + gtk-doc-for-gtk4/gtkdoc/mkhtml2.py | 1871 +++++ gtk-doc-for-gtk4/gtkdoc/mkman.py | 65 + gtk-doc-for-gtk4/gtkdoc/mkpdf.py | 122 + gtk-doc-for-gtk4/gtkdoc/rebase.py | 253 + gtk-doc-for-gtk4/gtkdoc/scan.py | 1172 +++ gtk-doc-for-gtk4/gtkdoc/scangobj.py | 1418 ++++ gtk-doc-for-gtk4/gtkdoc_uninstalled.py.in | 5 + gtk-doc-for-gtk4/help/Makefile.am | 7 + .../help/manual/C/fdl-appendix.xml | 671 ++ gtk-doc-for-gtk4/help/manual/C/index.docbook | 2601 +++++++ gtk-doc-for-gtk4/help/manual/ChangeLog | 157 + gtk-doc-for-gtk4/help/manual/LINGUAS | 17 + gtk-doc-for-gtk4/help/manual/Makefile.am | 17 + gtk-doc-for-gtk4/help/manual/bn_IN/bn_IN.po | 1341 ++++ gtk-doc-for-gtk4/help/manual/cs/cs.po | 5657 ++++++++++++++ gtk-doc-for-gtk4/help/manual/de/de.po | 6308 +++++++++++++++ gtk-doc-for-gtk4/help/manual/el/el.po | 6045 +++++++++++++++ gtk-doc-for-gtk4/help/manual/en_GB/en_GB.po | 2498 ++++++ gtk-doc-for-gtk4/help/manual/es/es.po | 6858 +++++++++++++++++ gtk-doc-for-gtk4/help/manual/fr/fr.po | 6647 ++++++++++++++++ gtk-doc-for-gtk4/help/manual/gl/gl.po | 3842 +++++++++ gtk-doc-for-gtk4/help/manual/gu/gu.po | 1470 ++++ gtk-doc-for-gtk4/help/manual/meson.build | 9 + gtk-doc-for-gtk4/help/manual/pt_BR/pt_BR.po | 6730 ++++++++++++++++ gtk-doc-for-gtk4/help/manual/sl/sl.po | 1460 ++++ gtk-doc-for-gtk4/help/manual/sv/sv.po | 6545 ++++++++++++++++ gtk-doc-for-gtk4/help/manual/ta/ta.po | 1340 ++++ gtk-doc-for-gtk4/help/manual/te/te.po | 1502 ++++ gtk-doc-for-gtk4/help/manual/zh_CN/zh_CN.po | 4241 ++++++++++ gtk-doc-for-gtk4/help/meson.build | 3 + gtk-doc-for-gtk4/m4/ax_python_module.m4 | 56 + .../m4/gtkdoc_jh_check_xml_catalog.m4 | 16 + .../m4/gtkdoc_jh_path_xml_catalog.m4 | 61 + gtk-doc-for-gtk4/meson.build | 193 + gtk-doc-for-gtk4/meson_options.txt | 12 + gtk-doc-for-gtk4/requirements.txt | 1 + gtk-doc-for-gtk4/style/COPYING | 17 + gtk-doc-for-gtk4/style/home.png | Bin 0 -> 256 bytes gtk-doc-for-gtk4/style/left-insensitive.png | Bin 0 -> 395 bytes gtk-doc-for-gtk4/style/left.png | Bin 0 -> 262 bytes gtk-doc-for-gtk4/style/meson.build | 15 + gtk-doc-for-gtk4/style/right-insensitive.png | Bin 0 -> 373 bytes gtk-doc-for-gtk4/style/right.png | Bin 0 -> 261 bytes gtk-doc-for-gtk4/style/style.css | 456 ++ gtk-doc-for-gtk4/style/up-insensitive.png | Bin 0 -> 374 bytes gtk-doc-for-gtk4/style/up.png | Bin 0 -> 260 bytes gtk-doc-for-gtk4/tests/Makefile.am | 57 + gtk-doc-for-gtk4/tests/annotations.sh | 6 + .../tests/annotations/Makefile.am | 11 + .../tests/annotations/docs/Makefile.am | 75 + .../tests/annotations/docs/meson.build | 107 + .../tests/annotations/docs/tester-docs.xml | 59 + .../annotations/docs/tester-sections.txt | 33 + .../tests/annotations/meson.build | 1 + .../tests/annotations/src/Makefile.am | 15 + .../tests/annotations/src/tester.c | 354 + .../tests/annotations/src/tester.h | 53 + gtk-doc-for-gtk4/tests/bugs.sh | 6 + gtk-doc-for-gtk4/tests/bugs/Makefile.am | 12 + gtk-doc-for-gtk4/tests/bugs/docs/Makefile.am | 77 + gtk-doc-for-gtk4/tests/bugs/docs/meson.build | 107 + .../tests/bugs/docs/tester-docs.xml | 36 + .../tests/bugs/docs/tester-sections.txt | 77 + gtk-doc-for-gtk4/tests/bugs/meson.build | 1 + gtk-doc-for-gtk4/tests/bugs/src/Makefile.am | 15 + gtk-doc-for-gtk4/tests/bugs/src/tester.c | 436 ++ gtk-doc-for-gtk4/tests/bugs/src/tester.h | 498 ++ gtk-doc-for-gtk4/tests/check.py | 56 + gtk-doc-for-gtk4/tests/common.py | 68 + gtk-doc-for-gtk4/tests/empty.sh | 11 + gtk-doc-for-gtk4/tests/empty/Makefile.am | 13 + gtk-doc-for-gtk4/tests/empty/docs/Makefile.am | 86 + gtk-doc-for-gtk4/tests/empty/docs/meson.build | 107 + gtk-doc-for-gtk4/tests/empty/meson.build | 1 + gtk-doc-for-gtk4/tests/empty/src/Makefile.am | 15 + gtk-doc-for-gtk4/tests/empty/src/tester.c | 33 + gtk-doc-for-gtk4/tests/empty/src/tester.h | 28 + gtk-doc-for-gtk4/tests/fail.sh | 41 + gtk-doc-for-gtk4/tests/fail/Makefile.am | 12 + gtk-doc-for-gtk4/tests/fail/docs/Makefile.am | 75 + gtk-doc-for-gtk4/tests/fail/docs/meson.build | 107 + .../tests/fail/docs/tester-docs.xml | 36 + .../tests/fail/docs/tester-sections.txt | 29 + gtk-doc-for-gtk4/tests/fail/meson.build | 1 + gtk-doc-for-gtk4/tests/fail/src/Makefile.am | 15 + gtk-doc-for-gtk4/tests/fail/src/tester.c | 70 + gtk-doc-for-gtk4/tests/fail/src/tester.h | 109 + gtk-doc-for-gtk4/tests/gobject.sh | 6 + gtk-doc-for-gtk4/tests/gobject/Makefile.am | 13 + .../tests/gobject/docs/Makefile.am | 80 + .../tests/gobject/docs/images/meson.build | 3 + .../tests/gobject/docs/images/object.png | Bin 0 -> 4101 bytes .../tests/gobject/docs/meson.build | 126 + .../tests/gobject/docs/tester-docs.xml | 119 + .../tests/gobject/docs/tester-sections.txt | 81 + .../tests/gobject/examples/gobject.c | 21 + gtk-doc-for-gtk4/tests/gobject/meson.build | 2 + .../tests/gobject/src/Makefile.am | 17 + gtk-doc-for-gtk4/tests/gobject/src/giface.c | 123 + gtk-doc-for-gtk4/tests/gobject/src/giface.h | 76 + gtk-doc-for-gtk4/tests/gobject/src/gobject.c | 457 ++ gtk-doc-for-gtk4/tests/gobject/src/gobject.h | 158 + gtk-doc-for-gtk4/tests/gobject/src/gtypes.c | 77 + gtk-doc-for-gtk4/tests/gobject/src/gtypes.h | 78 + .../tests/gobject/src/meson.build | 30 + gtk-doc-for-gtk4/tests/gtk-doc.make | 231 + gtk-doc-for-gtk4/tests/gtkdoctest.sh | 7 + .../tests/helpers/gtkdoc_check_runner.py | 30 + .../tests/helpers/gtkdoc_fixxref_runner.py | 27 + .../tests/helpers/gtkdoc_mkdb_runner.py | 27 + .../tests/helpers/gtkdoc_mkhtml_runner.py | 38 + .../tests/helpers/gtkdoc_scan_runner.py | 27 + .../tests/helpers/gtkdoc_scangobj_runner.py | 54 + gtk-doc-for-gtk4/tests/helpers/meson.build | 6 + gtk-doc-for-gtk4/tests/highlight.py | 34 + gtk-doc-for-gtk4/tests/meson.build | 45 + gtk-doc-for-gtk4/tests/mk_to_db.py | 289 + gtk-doc-for-gtk4/tests/mkdb.py | 288 + gtk-doc-for-gtk4/tests/mkhtml2.py | 490 ++ gtk-doc-for-gtk4/tests/program.sh | 6 + gtk-doc-for-gtk4/tests/program/Makefile.am | 11 + .../tests/program/docs/Makefile.am | 76 + .../tests/program/docs/meson.build | 106 + .../tests/program/docs/tester-docs.xml | 32 + .../tests/program/docs/tester-sections.txt | 0 gtk-doc-for-gtk4/tests/program/meson.build | 1 + .../tests/program/src/Makefile.am | 10 + .../tests/program/src/test-program.c | 19 + gtk-doc-for-gtk4/tests/repro/Makefile.am | 12 + gtk-doc-for-gtk4/tests/repro/docs/Makefile.am | 78 + gtk-doc-for-gtk4/tests/repro/docs/meson.build | 106 + .../tests/repro/docs/tester-docs.xml | 28 + gtk-doc-for-gtk4/tests/repro/meson.build | 1 + gtk-doc-for-gtk4/tests/repro/src/Makefile.am | 15 + gtk-doc-for-gtk4/tests/repro/src/tester.c | 8 + gtk-doc-for-gtk4/tests/repro/src/tester.h | 14 + gtk-doc-for-gtk4/tests/sanity.sh | 155 + gtk-doc-for-gtk4/tests/scan.py | 948 +++ gtk-doc-for-gtk4/tests/tools.sh.in | 46 + gtk-doc-for-gtk4/tools/c10e-html.py | 58 + gtk-doc-for-gtk4/tools/db2md.py | 212 + gtk-doc-for-gtk4/tools/docpercentages.pl | 155 + gtk-doc-for-gtk4/tools/git-pre-commit | 27 + gtk-doc-for-gtk4/tools/gtk-doc.el | 294 + gtk-doc-for-gtk4/version-greater-or-equal.xsl | 54 + 209 files changed, 100557 insertions(+) create mode 100644 gtk-doc-for-gtk4/AUTHORS create mode 100644 gtk-doc-for-gtk4/COPYING create mode 100644 gtk-doc-for-gtk4/COPYING-DOCS create mode 100644 gtk-doc-for-gtk4/ChangeLog create mode 100644 gtk-doc-for-gtk4/HACKING create mode 100644 gtk-doc-for-gtk4/MAINTAINERS create mode 100644 gtk-doc-for-gtk4/Makefile.am create mode 100644 gtk-doc-for-gtk4/NEWS create mode 100644 gtk-doc-for-gtk4/README create mode 100644 gtk-doc-for-gtk4/TODO create mode 100755 gtk-doc-for-gtk4/autogen.sh create mode 100755 gtk-doc-for-gtk4/bugzilla.py create mode 100644 gtk-doc-for-gtk4/buildsystems/autotools/Makefile.am create mode 100644 gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.m4 create mode 100644 gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.make create mode 100644 gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.no-xslt.make create mode 100755 gtk-doc-for-gtk4/buildsystems/autotools/gtkdocize.in create mode 100644 gtk-doc-for-gtk4/buildsystems/autotools/meson.build create mode 100644 gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfig.cmake create mode 100644 gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfigVersion.cmake.in create mode 100644 gtk-doc-for-gtk4/buildsystems/cmake/GtkDocScanGObjWrapper.cmake create mode 100644 gtk-doc-for-gtk4/buildsystems/cmake/Makefile.am create mode 100644 gtk-doc-for-gtk4/buildsystems/cmake/meson.build create mode 100644 gtk-doc-for-gtk4/configure.ac create mode 100644 gtk-doc-for-gtk4/devhelp2.xsd create mode 100644 gtk-doc-for-gtk4/devhelp2.xsl create mode 100644 gtk-doc-for-gtk4/doc/README create mode 100644 gtk-doc-for-gtk4/doc/authors.txt create mode 100644 gtk-doc-for-gtk4/doc/design-1.x.txt create mode 100644 gtk-doc-for-gtk4/doc/design-2.x.txt create mode 100644 gtk-doc-for-gtk4/doc/gnome.txt create mode 100644 gtk-doc-for-gtk4/doc/gtkdoc.dot create mode 100644 gtk-doc-for-gtk4/doc/sections-file.txt create mode 100644 gtk-doc-for-gtk4/doc/setting-up.txt create mode 100644 gtk-doc-for-gtk4/doc/style-guide.txt create mode 100644 gtk-doc-for-gtk4/examples/Makefile.am create mode 100644 gtk-doc-for-gtk4/examples/README create mode 100644 gtk-doc-for-gtk4/git.mk create mode 100644 gtk-doc-for-gtk4/gtk-doc-fo.xsl create mode 100644 gtk-doc-for-gtk4/gtk-doc.doap create mode 100644 gtk-doc-for-gtk4/gtk-doc.pc.in create mode 100644 gtk-doc-for-gtk4/gtk-doc.xsl create mode 100755 gtk-doc-for-gtk4/gtkdoc-check.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-depscan.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-fixxref.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-mkdb.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-mkhtml.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-mkhtml2.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-mkman.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-mkpdf.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-rebase.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-scan.in create mode 100755 gtk-doc-for-gtk4/gtkdoc-scangobj.in create mode 100644 gtk-doc-for-gtk4/gtkdoc/__init__.py create mode 100755 gtk-doc-for-gtk4/gtkdoc/check.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/common.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/config.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/config_data.py.in create mode 100755 gtk-doc-for-gtk4/gtkdoc/fixxref.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/highlight.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/md_to_db.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/meson.build create mode 100644 gtk-doc-for-gtk4/gtkdoc/mkdb.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/mkhtml.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/mkhtml2.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/mkman.py create mode 100755 gtk-doc-for-gtk4/gtkdoc/mkpdf.py create mode 100755 gtk-doc-for-gtk4/gtkdoc/rebase.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/scan.py create mode 100644 gtk-doc-for-gtk4/gtkdoc/scangobj.py create mode 100644 gtk-doc-for-gtk4/gtkdoc_uninstalled.py.in create mode 100644 gtk-doc-for-gtk4/help/Makefile.am create mode 100644 gtk-doc-for-gtk4/help/manual/C/fdl-appendix.xml create mode 100644 gtk-doc-for-gtk4/help/manual/C/index.docbook create mode 100644 gtk-doc-for-gtk4/help/manual/ChangeLog create mode 100644 gtk-doc-for-gtk4/help/manual/LINGUAS create mode 100644 gtk-doc-for-gtk4/help/manual/Makefile.am create mode 100644 gtk-doc-for-gtk4/help/manual/bn_IN/bn_IN.po create mode 100644 gtk-doc-for-gtk4/help/manual/cs/cs.po create mode 100644 gtk-doc-for-gtk4/help/manual/de/de.po create mode 100644 gtk-doc-for-gtk4/help/manual/el/el.po create mode 100644 gtk-doc-for-gtk4/help/manual/en_GB/en_GB.po create mode 100644 gtk-doc-for-gtk4/help/manual/es/es.po create mode 100644 gtk-doc-for-gtk4/help/manual/fr/fr.po create mode 100644 gtk-doc-for-gtk4/help/manual/gl/gl.po create mode 100644 gtk-doc-for-gtk4/help/manual/gu/gu.po create mode 100644 gtk-doc-for-gtk4/help/manual/meson.build create mode 100644 gtk-doc-for-gtk4/help/manual/pt_BR/pt_BR.po create mode 100644 gtk-doc-for-gtk4/help/manual/sl/sl.po create mode 100644 gtk-doc-for-gtk4/help/manual/sv/sv.po create mode 100644 gtk-doc-for-gtk4/help/manual/ta/ta.po create mode 100644 gtk-doc-for-gtk4/help/manual/te/te.po create mode 100644 gtk-doc-for-gtk4/help/manual/zh_CN/zh_CN.po create mode 100644 gtk-doc-for-gtk4/help/meson.build create mode 100644 gtk-doc-for-gtk4/m4/ax_python_module.m4 create mode 100644 gtk-doc-for-gtk4/m4/gtkdoc_jh_check_xml_catalog.m4 create mode 100644 gtk-doc-for-gtk4/m4/gtkdoc_jh_path_xml_catalog.m4 create mode 100644 gtk-doc-for-gtk4/meson.build create mode 100644 gtk-doc-for-gtk4/meson_options.txt create mode 100644 gtk-doc-for-gtk4/requirements.txt create mode 100644 gtk-doc-for-gtk4/style/COPYING create mode 100644 gtk-doc-for-gtk4/style/home.png create mode 100644 gtk-doc-for-gtk4/style/left-insensitive.png create mode 100644 gtk-doc-for-gtk4/style/left.png create mode 100644 gtk-doc-for-gtk4/style/meson.build create mode 100644 gtk-doc-for-gtk4/style/right-insensitive.png create mode 100644 gtk-doc-for-gtk4/style/right.png create mode 100644 gtk-doc-for-gtk4/style/style.css create mode 100644 gtk-doc-for-gtk4/style/up-insensitive.png create mode 100644 gtk-doc-for-gtk4/style/up.png create mode 100644 gtk-doc-for-gtk4/tests/Makefile.am create mode 100755 gtk-doc-for-gtk4/tests/annotations.sh create mode 100644 gtk-doc-for-gtk4/tests/annotations/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/annotations/docs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/annotations/docs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/annotations/docs/tester-docs.xml create mode 100644 gtk-doc-for-gtk4/tests/annotations/docs/tester-sections.txt create mode 100644 gtk-doc-for-gtk4/tests/annotations/meson.build create mode 100644 gtk-doc-for-gtk4/tests/annotations/src/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/annotations/src/tester.c create mode 100644 gtk-doc-for-gtk4/tests/annotations/src/tester.h create mode 100755 gtk-doc-for-gtk4/tests/bugs.sh create mode 100644 gtk-doc-for-gtk4/tests/bugs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/bugs/docs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/bugs/docs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/bugs/docs/tester-docs.xml create mode 100644 gtk-doc-for-gtk4/tests/bugs/docs/tester-sections.txt create mode 100644 gtk-doc-for-gtk4/tests/bugs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/bugs/src/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/bugs/src/tester.c create mode 100644 gtk-doc-for-gtk4/tests/bugs/src/tester.h create mode 100755 gtk-doc-for-gtk4/tests/check.py create mode 100755 gtk-doc-for-gtk4/tests/common.py create mode 100755 gtk-doc-for-gtk4/tests/empty.sh create mode 100644 gtk-doc-for-gtk4/tests/empty/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/empty/docs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/empty/docs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/empty/meson.build create mode 100644 gtk-doc-for-gtk4/tests/empty/src/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/empty/src/tester.c create mode 100644 gtk-doc-for-gtk4/tests/empty/src/tester.h create mode 100755 gtk-doc-for-gtk4/tests/fail.sh create mode 100644 gtk-doc-for-gtk4/tests/fail/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/fail/docs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/fail/docs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/fail/docs/tester-docs.xml create mode 100644 gtk-doc-for-gtk4/tests/fail/docs/tester-sections.txt create mode 100644 gtk-doc-for-gtk4/tests/fail/meson.build create mode 100644 gtk-doc-for-gtk4/tests/fail/src/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/fail/src/tester.c create mode 100644 gtk-doc-for-gtk4/tests/fail/src/tester.h create mode 100755 gtk-doc-for-gtk4/tests/gobject.sh create mode 100644 gtk-doc-for-gtk4/tests/gobject/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/gobject/docs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/gobject/docs/images/meson.build create mode 100644 gtk-doc-for-gtk4/tests/gobject/docs/images/object.png create mode 100644 gtk-doc-for-gtk4/tests/gobject/docs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/gobject/docs/tester-docs.xml create mode 100644 gtk-doc-for-gtk4/tests/gobject/docs/tester-sections.txt create mode 100644 gtk-doc-for-gtk4/tests/gobject/examples/gobject.c create mode 100644 gtk-doc-for-gtk4/tests/gobject/meson.build create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/giface.c create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/giface.h create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/gobject.c create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/gobject.h create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/gtypes.c create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/gtypes.h create mode 100644 gtk-doc-for-gtk4/tests/gobject/src/meson.build create mode 100644 gtk-doc-for-gtk4/tests/gtk-doc.make create mode 100755 gtk-doc-for-gtk4/tests/gtkdoctest.sh create mode 100644 gtk-doc-for-gtk4/tests/helpers/gtkdoc_check_runner.py create mode 100644 gtk-doc-for-gtk4/tests/helpers/gtkdoc_fixxref_runner.py create mode 100644 gtk-doc-for-gtk4/tests/helpers/gtkdoc_mkdb_runner.py create mode 100644 gtk-doc-for-gtk4/tests/helpers/gtkdoc_mkhtml_runner.py create mode 100644 gtk-doc-for-gtk4/tests/helpers/gtkdoc_scan_runner.py create mode 100644 gtk-doc-for-gtk4/tests/helpers/gtkdoc_scangobj_runner.py create mode 100644 gtk-doc-for-gtk4/tests/helpers/meson.build create mode 100755 gtk-doc-for-gtk4/tests/highlight.py create mode 100644 gtk-doc-for-gtk4/tests/meson.build create mode 100755 gtk-doc-for-gtk4/tests/mk_to_db.py create mode 100755 gtk-doc-for-gtk4/tests/mkdb.py create mode 100755 gtk-doc-for-gtk4/tests/mkhtml2.py create mode 100755 gtk-doc-for-gtk4/tests/program.sh create mode 100644 gtk-doc-for-gtk4/tests/program/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/program/docs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/program/docs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/program/docs/tester-docs.xml create mode 100644 gtk-doc-for-gtk4/tests/program/docs/tester-sections.txt create mode 100644 gtk-doc-for-gtk4/tests/program/meson.build create mode 100644 gtk-doc-for-gtk4/tests/program/src/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/program/src/test-program.c create mode 100644 gtk-doc-for-gtk4/tests/repro/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/repro/docs/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/repro/docs/meson.build create mode 100644 gtk-doc-for-gtk4/tests/repro/docs/tester-docs.xml create mode 100644 gtk-doc-for-gtk4/tests/repro/meson.build create mode 100644 gtk-doc-for-gtk4/tests/repro/src/Makefile.am create mode 100644 gtk-doc-for-gtk4/tests/repro/src/tester.c create mode 100644 gtk-doc-for-gtk4/tests/repro/src/tester.h create mode 100755 gtk-doc-for-gtk4/tests/sanity.sh create mode 100755 gtk-doc-for-gtk4/tests/scan.py create mode 100644 gtk-doc-for-gtk4/tests/tools.sh.in create mode 100755 gtk-doc-for-gtk4/tools/c10e-html.py create mode 100644 gtk-doc-for-gtk4/tools/db2md.py create mode 100755 gtk-doc-for-gtk4/tools/docpercentages.pl create mode 100755 gtk-doc-for-gtk4/tools/git-pre-commit create mode 100644 gtk-doc-for-gtk4/tools/gtk-doc.el create mode 100644 gtk-doc-for-gtk4/version-greater-or-equal.xsl diff --git a/gtk-doc-for-gtk4/AUTHORS b/gtk-doc-for-gtk4/AUTHORS new file mode 100644 index 0000000000..7eb7261971 --- /dev/null +++ b/gtk-doc-for-gtk4/AUTHORS @@ -0,0 +1,3 @@ +Damon Chaplin +Owen Taylor + diff --git a/gtk-doc-for-gtk4/COPYING b/gtk-doc-for-gtk4/COPYING new file mode 100644 index 0000000000..d60c31a97a --- /dev/null +++ b/gtk-doc-for-gtk4/COPYING @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/gtk-doc-for-gtk4/COPYING-DOCS b/gtk-doc-for-gtk4/COPYING-DOCS new file mode 100644 index 0000000000..1a864561bd --- /dev/null +++ b/gtk-doc-for-gtk4/COPYING-DOCS @@ -0,0 +1,355 @@ + GNU Free Documentation License + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. diff --git a/gtk-doc-for-gtk4/ChangeLog b/gtk-doc-for-gtk4/ChangeLog new file mode 100644 index 0000000000..352073cd0e --- /dev/null +++ b/gtk-doc-for-gtk4/ChangeLog @@ -0,0 +1,5020 @@ +2009-04-15 Stefan Kost + + * autogen.sh: + * configure.in: + Tentative patch to allow building without scrollkeeper and + gnome-doc-utils. Fixes #577059. + +2009-04-05 Stefan Kost + + * examples/Makefile.am: + Only run the tests if gtk-doc is enabled. Fixes #577774. + +2009-03-18 Stefan Kost + + patch by: David Nečas + + * gtkdoc-fixxref.in: + Fix element mismatch in highlighted code. Fixes #575711. + +2009-03-17 Stefan Kost + + * gtk-doc.m4: + Turn pdf off if there is no gtkdoc-mkpdf installed. + +2009-03-17 Stefan Kost + + patch by: Tobias Mueller + + * COPYING-DOCS: + * gtkdoc-check.in: + * gtkdoc-common.pl.in: + * gtkdoc-fixxref.in: + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + * gtkdoc-rebase.in: + * gtkdoc-scan.in: + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + * help/manual/C/fdl-appendix.xml: + * tools/gtk-doc.el: + Update FSF address. Fixes #575623. + +2009-03-17 Stefan Kost + + * gtkdoc-mkpdf.in: + Don't run fop for now, its way to broken. + + * tests/bugs/src/tester.h: + Formatting. + +2009-03-17 Stefan Kost + + patch by: Vincent Untz + + * gtkdoc-common.pl.in: + Be more friendly for files with a space in their name. Fixes #575574. + +2009-03-12 Stefan Kost + + * gtkdoc-mkdb.in: + Do not overwrite declaration variable with sgml-ified variant to not confuse + further parsing. + +2009-03-10 Stefan Kost + + patch by: Nicola Fontana + + * gtkdoc-scan.in: + * tests/bugs/docs/Makefile.am: + * tests/bugs/src/tester.h: + Improve the test and fix handling trailing decorators. Fixes #574654 + +2009-03-10 Stefan Kost + + * tests/bugs/docs/Makefile.am: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: + * tests/bugs/src/tester.h: + Adding a test for #574654. + +2009-03-10 Stefan Kost + + * gtkdoc-fixxref.in: + Don't expect $MODULE to be defined (e.g. if someone does not update + gtkdoc.make). + +2009-03-09 Stefan Kost + + * ChangeLog: + Fix ChangeLog format so that we pick up the bug number for release + notes. + +2009-03-09 Stefan Kost + + patch by: David Nečas + + * configure.in: + * gtkdoc-fixxref.in: + Add vim support for syntax highlighting. Lets close the ticket. + Fixes #536928. + +2009-03-09 Stefan Kost + + * gtkdoc-scangobj.in: + Don't confuse -1 with G_MAXULONG on 64bit. Fixes #572612. + +2009-02-26 Stefan Kost + + * doc/gtkdoc.dot: + Improve. scan only checks headers, while mkdb scans sources and + headers. + + * examples/Makefile.am: + Document more variables. + +2009-02-26 Stefan Kost + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + There is some gtk specific stuff there, which we probably want to kick + out. No one else gets such a treatment. + +2009-02-26 Stefan Kost + + * gtk-doc.xsl: + * style.css: + * gtkdoc-mkdb.in: + Fix annotation more. Refactor the extra-link feature. Still disabled + by default. Needs configure stuff next. + +2009-02-24 Stefan Kost + + patch by: Paolo Borelli + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + Use g_strerror. Fixes #572967. + +2009-02-23 Sven Herzberg + + * gtkdoc-scangobj.in: keep a reference on the GObjectClass while + peeking in interfaces' properties. Fixes #571820 + +2009-02-23 Stefan Kost + + * gtkdoc-mkdb.in: + Don't use named entities. + +2009-02-23 Stefan Kost + + * gtk-doc-single.xsl: + Starting point for generating single page html. Needs refactoring with + gtk-doc.xsl (common stuff into gtk-doc-html.xsl). + +2009-02-23 Stefan Kost + + * TODO: + With fop-0.94 it works actually, while 0.95 seesm to have the + exceptions. + + * gtkdoc-mkpdf.in: + Fix var reference. + +2009-02-22 Stefan Kost + + * TODO: + * gtkdoc-mkdb.in: + Prototype an idea. + +2009-02-22 Stefan Kost + + * Makefile.am: + Dist more files. + + * configure.in: + Update status. + + * gtkdoc-mkpdf.in: + Remove some crack left from copy'n'paste. + +2009-02-22 Stefan Kost + + * TODO: + Planning. + + * configure.in: + * gtk-doc.m4: + * gtk-doc.make: + * gtk-doc.notmpl.make: + * gtkdoc-mkpdf.in: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + * gtkdoc-mkpdf.in (added): + Clean up Makefile rules (be less verbose). Added options to configure to + allow selecting the desired output formats. Added initial pdf support (very + imature yet, due to several shortcommings of fop - bugs files). + +2009-02-21 Stefan Kost + + * TODO: + Planning. + + * gtkdoc-mkdb.in: + Update annotations and fix matching to support parameters. + + * tests/annotations/docs/tester-sections.txt: + * tests/annotations/src/tester.c: + * tests/annotations/src/tester.h: + Update annotation example and add one more. + +2009-02-21 Stefan Kost + + * gtkdoc-mkdb.in: + * help/manual/C/gtk-doc-manual.xml: + * tests/gobject/src/gobject.c: + Allow linking to struct members. Update docs. Fixes #565126. + +2009-02-21 Stefan Kost + + * configure.in: + * gtkdoc-fixxref.in: + Fix params and running of 'highlight'. + +2009-02-21 Stefan Kost + + * gtkdoc-mkdb.in: + Require the line to ends after the double-colon (sans whitespace), + +2009-02-20 Stefan Kost + + patch by: Damien Lespiau + + * gtk-doc.make: + * gtk-doc.notmpl.make: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Add --tag=CC to libtool invocations. Fixes #572396. + +2009-02-18 Stefan Kost + + * examples/Makefile.am: + Fix example to show to to make it work even with make distcheck. + +2009-02-16 Stefan Kost + + * style.css: + * tests/gobject/src/gobject.c: + Also style tags. + +2009-02-10 Stefan Kost + + * MAINTAINERS: + Fix the spelling of my name. + +2009-02-05 Stefan Kost + + * TODO: + Some planning. + + * gtkdoc-mkdb.in: + Single tabs are rendered inconsistently in browsers. Replace them with + a  . + +2009-01-31 Stefan Kost + + * tests/gobject/src/gobject.c: + Try to link to struct members as a test for Bug #565126. + +2009-01-30 Stefan Kost + + * gtkdoc-mkdb.in: + Expanding urls is not a good idea yet. Need to figure out. + +2009-01-29 Stefan Kost + + * tests/tools.sh: + Remove, this is generated. + +2009-01-29 Stefan Kost + + * gtkdoc-mkdb.in: + Automatically creating ulinks for urls. + + * tests/gobject/src/gobject.c: + Add a link for testing. + +2009-01-28 Stefan Kost + + * style-classic.css: + * style.css: + * tests/gobject/docs/tester-docs.xml: + * tests/gobject/src/gobject.c: + Major CSS cleanup. This is hopefully an end of layout issues related + to the fixed navigation bar. + +2009-01-28 Stefan Kost + + patch by: David Nečas + + * gtkdoc-mkdb.in: + * tests/gobject/src/giface.c: + * tests/gobject/src/gobject.c: + Abbreviation where not expanded at the start of text. Fixes #569339. + +2009-01-28 Stefan Kost + + * gtkdoc-fixxref.in: + * tests/gobject/examples/gobject.c: + Expand urls in comments of examples. + +2009-01-27 Stefan Kost + + * gtkdoc-fixxref.in: + * style.css: + Use tables like described in #536928. + + * tests/tools.sh + Comment on why we do the tool check like this. + + * tests/fail.sh: + Comment on test. + + * tests/gobject/docs/tester-docs.xml: + Fix xml a bit. + +2009-01-26 Stefan Kost + + * gtkdoc-mkdb.in: + * tests/bugs/src/tester.h: + * tests/fail.sh: + * tests/fail/docs/tester-docs.xml: + * tests/fail/docs/tester-sections.txt: + * tests/fail/src/tester.c: + Add public symbols from section file when doing the -undocumented.txt + report. Also add the special symbols for the section docs when reading + the section-file. Extend test suite to check for it. Fixes #568732 + +2009-01-26 Stefan Kost + + * gtkdoc-scan.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: + * tests/bugs/src/tester.h: + Handle inline functions in headers. Fixes #532395. + +2009-01-26 Stefan Kost + + * HACKING: + Mention onine site for regexp testing. + + * gtkdoc-mkdb.in: + Small output cleanups. + + * gtkdoc-mktmpl.in: + Indenting and use LogWarning once more. + +2009-01-23 Stefan Kost + + * gtkdoc-mkdb.in: + Recomment out debug log the accidentialy went in. + + * configure.in: + * tests/Makefile.am: + * tests/fail.sh: + * tests/tools.sh.in: + * tests/tools.sh.in (added): + Add a check that tests that all scripts are runnable. + +2009-01-23 Stefan Kost + + * gtkdoc-check.in: + No need to format a '\n' into a formatstring. + + * gtkdoc-mkdb.in: + Add FIXMEs for Bug 568711. + + * gtkdoc-mkhtml.in: + Add a comment. + + * configure.in: + * tests/Makefile.am: + * tests/fail.sh: + * tests/fail/Makefile.am: + * tests/fail/docs/Makefile.am: + * tests/fail/docs/tester-docs.xml: + * tests/fail/docs/tester-sections.txt: + * tests/fail/src/Makefile.am: + * tests/fail/src/tester.c: + * tests/fail/src/tester.h: + Add a test suite for failure checks. + +2009-01-23 Stefan Kost + + patch by: David Nečas + + * gtkdoc-scan.in: + Don't scan files twice. The patch was slightly changed to name the + hash lowercase (uppercase is used for configureation options) and + add a comment. Fixes #568708. + +2009-01-23 Stefan Kost + + patch by: David Nečas + + * gtkdoc-mkdb.in: + Don't add empty tags to the docs to avoid breaking the + detection of undocumented things. Fixes #568732. + +2009-01-23 Stefan Kost + + patch by: David Nečas + + * gtk-doc.m4: + Change nonsense error message to tell that gtk-doc is needed to build + a given package and not gtk-doc. Fixes #568734. + +2009-01-23 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-scan.in: + Treat iface/interface like class in other places too. + +2009-01-23 Stefan Kost + + patch by: David Nečas + + * gtkdoc-scan.in: + Use CamelCase id for interfaces. Fixes #568706. + +2009-01-23 Stefan Kost + + patch by: David Nečas + + * gtkdoc-mkhtml.in: + * gtkdoc-mkman.in: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Less quirky way of knowing that we run uninstalled, which is only + needed for the tests anyway. In addition to the patch, make same + changes in mkman, add a shift to arg parsing to not loop and change + the makefiles for the tests. Fixes #568702. + +2009-01-22 Stefan Kost + + * gtkdoc-fixxref.in: + Only run the syntax highligher if we have one. Fixes #568714. + +2009-01-22 Stefan Kost + + * README: + Point to the right docs. + + * TODO: + More tinking. + + * style.css: + Remove one commented out item. + +2009-01-21 Stefan Kost + + * TODO: + * configure.in: + * gtkdoc-fixxref.in: + * style.css: + Match css of highlight with source-highlight. Handle line numbering by + our-selfs. Still stupid browsers copy '#' chars for each line number. + +2009-01-21 Stefan Kost + + * gtkdoc-fixxref.in: + Try to xref first word in 'normal' span. + +2009-01-20 Stefan Kost + + * TODO: + * gtkdoc-mkdb.in: + * tests/gobject/src/gobject.c: + We could add the language as a comment, it is not shown in the final output. + +2009-01-20 Stefan Kost + + * TODO: + More ideas. + + * gtkdoc-fixxref.in: + Really fix double extension of entities. + + * style.css: + Fix link color of xrefs symbols. + +2009-01-20 Stefan Kost + + * gtkdoc-fixxref.in: + Indent. + + * gtkdoc-mkdb.in: + Fix end of string handling. + + * style.css: + Use one tango colors one more time. + +2009-01-20 Stefan Kost + + * gtkdoc-mkdb.in: + * tests/annotations/docs/Makefile.am: + * tests/bugs/docs/Makefile.am: + * tests/bugs/docs/tester-docs.xml: + * tests/gobject/docs-tmpl/Makefile.am: + * tests/gobject/docs/Makefile.am: + Detect namespace prefix if not given. + +2009-01-20 Stefan Kost + + * style-classic.css: + * style.css: + Fix gap, caused by double index divs produces by index generated with + the docbook stylesheets. + +2009-01-20 Stefan Kost + + * TODO: + More ideas. + + * gtk-doc.xsl: + Make sure indexdiv and glossarydiv elements have anchors. + + * style-classic.css: + * style.css: + Fix spacing for navbar in index/glossary pages. + + * tests/annotations/docs/tester-docs.xml: + * tests/gobject/docs/tester-docs.xml: + Cleanup samples. + +2009-01-19 Stefan Kost + + * TODO: + More ideas. + + * gtk-doc.xsl: + Experiment with navigation for index and glossaries. + + * gtkdoc-fixxref.in: + * gtkdoc-mkdb.in: + Fix index entries and copy doc along with the method. + + * style.css: + also do the extra spacing for the index/glossary environments now. + + * tests/gobject/docs/tester-docs.xml: + Experiment with a more complete doc structure. + +2009-01-12 Stefan Kost + + * gtkdoc-fixxref.in: + Make highligher post processing conditional. + +2009-01-10 Stefan Kost + + * configure.in: + Erm, not having a highlighter is not fatal. + +2009-01-10 Stefan Kost + + * HACKING: + * TODO: + * configure.in: + * gtkdoc-fixxref.in: + Look for source-highlight and highlight. Not perfect yet, highlight uses + different classes in the css :/. + + * tests/gobject/docs/tester-docs.xml: + More header data in the examples. + +2009-01-09 Stefan Kost + + patch by: David Nečas + + * gtkdoc-scan.in: + Treat FOO_GET_INTERFACE as standard. Fixes #567132. + +2009-01-09 Stefan Kost + + * TODO: + * gtk-doc.make: + * gtk-doc.notmpl.make: + * gtkdoc-fixxref.in: + * gtkdoc-mkdb.in: + * style.css: + * tests/gobject/examples/gobject.c: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Initial go at implementing syntax highlighting for sources using + gnu source-highlight. Needs testing and modularisation. + +2009-01-08 Stefan Kost + + * gtkdoc-mkhtml.in: + Comment out echo for debugging. + +2009-01-08 Stefan Kost + + * gtk-doc.make: + * gtkdoc-mkhtml.in: + * tests/gobject/docs-tmpl/Makefile.am: + * tests/gobject/docs/Makefile.am: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Finally, make distcheck works. + +2009-01-08 Stefan Kost + + * gtkdoc-check.in: + * gtkdoc-depscan.in: + * gtkdoc-fixxref.in: + * gtkdoc-mkdb.in: + * gtkdoc-mkhtml.in: + * gtkdoc-mkman.in: + * gtkdoc-mktmpl.in: + * gtkdoc-rebase.in: + * gtkdoc-scan.in: + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + * gtkdocize.in: + Add support for --help and --version to remaining tools. Also show a + short info on --help and format more consistently. Fixes #566911 + +2009-01-07 Stefan Kost + + * gtk-doc.m4: + * gtk-doc.make: + * gtk-doc.notmpl.make: + Detect gtkdoc-rebase in gtk-doc.m4. Based on idea of Sven Herzberg. + Fixes #562310 + +2009-01-07 Stefan Kost + + * NEWS: + Prepare for 1.12. + + * TODO: + More thinking about the documentation structure. + + * configure.in: + Add automake support for more distcheck. Use a real sourcefile for the + srcdir (something that we won't remove one day). + + * tests/annotations/docs/Makefile.am: + * tests/annotations/src/Makefile.am: + * tests/bugs/docs/Makefile.am: + * tests/bugs/src/Makefile.am: + * tests/gobject/docs-tmpl/Makefile.am: + * tests/gobject/docs/Makefile.am: + * tests/gobject/src/Makefile.am: + Add missing file to fix make distcheck. Use srcdir and not builddir to + locate includes. + +2009-01-07 Stefan Kost + + * TODO: + Ideas about syntax highlighting. + + * style-classic.css: + Old color scheme. + + * style.css: + Use tango colors. Simplify css. + + * tests/gobject/src/gobject.c: + Tell what language this is. + +2009-01-04 Stefan Kost + + * tests/bugs/src/tester.c: + Fix inconsistency of prototype and docs. + +2009-01-04 Stefan Kost + + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Now all tests pass. + +2009-01-04 Stefan Kost + + * gtkdoc-mkhtml.in: + * tests/Makefile.am: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + * tests/gtkdoctest.sh: + Fix running tests, if no gtk-doc is installed yet. + +2008-12-29 Stefan Kost + + patch by: Bruce van der Kooij + + * help/manual/C/gtk-doc-manual.xml: + Fixed three spelling errors (recommanded, conatins, alibrary). + Fixes #565835. + +2008-12-29 Stefan Kost + + * TODO: + Documentation structure ideas. + +2008-12-05 Stefan Kost + + * style.css: + Highlight deprecation warnings. + +2008-12-04 Stefan Kost + + * gtkdoc-mkdb.in: + Fix escaping. + +2008-12-02 Stefan Kost + + * TODO: + Planning. + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Remove the sh -c here now that its back in scanobj. + + * tests/annotations/docs/tester-docs.xml: + * tests/bugs/docs/tester-docs.xml: + * tests/gobject/docs-tmpl/tester-docs.xml: + * tests/gobject/docs/tester-docs.xml: + Cosmetic template update. + +2008-12-02 Stefan Kost + + * gtkdoc-mkdb.in: + Don't touch doctype header in expand-content-files. + +2008-12-01 Stefan Kost + + * gtkdoc-mkdb.in: + Add deprecation warnings for signals and properties. Also reuse code + for since and stability levels there. Fixes #562655. + + * tests/gobject/src/gobject.c: + Add testcase for #562655. + +2008-12-01 Stefan Kost + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + Reintroduce "sh -c" and comment why its used. Add real libtool support + to old scanobj tool as well. + +2008-12-01 Stefan Kost + + patch by: Matthias Clasen + + * gtkdoc-mkdb.in: + Fix index-id generation for child and style properties. Fixes #562064. + +2008-11-16 Stefan Kost + + * HACKING: + * configure.in: + * help/manual/C/gtk-doc-manual.xml: + Back to development. + +=== Release 1.11 === + +2008-11-16 Stefan Kost + + * HACKING: + * NEWS: + Releasing 1.11. + + * tests/Makefile.am: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + * tests/gtkdoctest.sh: + Fix make distcheck. + +2008-11-06 Stefan Kost + + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + No install rules for test. + +2008-11-06 Stefan Kost + + * gtkdoc-mkdb.in: + Get rid of german variable name. Generate glossary xml for + annotations. Improve initial master document. + + * tests/annotations/docs/tester-docs.xml: + Update example to include anotation glossary. + +2008-11-05 Stefan Kost + + patch by: Peter Kjellerstedt + + * gtk-doc.make: + * gtk-doc.notmpl.make: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Correct check for existence of gtkdoc-rebase (better fix than the + previous one #508897). Fixes #559281. + +2008-10-27 Stefan Kost + + patch by: Christian Persch + + * gtkdoc-scangobj.in: + Fix doc build when using GTK_DISABLE_SINGLE_INCLUDES. Fixes #558082. + +2008-10-20 Stefan Kost + + * TODO: + * devhelp2.xsd: + More docs and planning. + +2008-10-20 Stefan Kost + + * tests/annotations/docs/tester-docs.xml: + * tests/annotations/src/tester.c: + * tests/gobject/docs/tester-docs.xml: + Update annotations. Glossary enhancements. + +2008-10-19 Stefan Kost + + * devhelp2.xsd: + Update and document format. + +2008-10-17 Stefan Kost + + * devhelp2.xsd: + * devhelp2.xsl: + Add new language attribute and use "c" here. + +2008-10-16 Stefan Kost + + * TODO: + * gtkdoc-mktmpl.in: + Small comment cleanup and loud thinking in TODO :) + +2008-10-15 Stefan Kost + + patch by: Jeffrey Stedfast + + * examples/Makefile.am: + * gtk-doc.make: + * gtk-doc.notmpl.make: + Allow versioned TARGET_DIR. Fixes #554718. + +2008-10-13 Stefan Kost + + * TODO: + planning. + + * doc/gtkdoc.dot: + Document workflow + * devhelp2.xsl: + Add support for enums/flags in devhelp index. + + * gtkdoc-mkdb.in: + Support annotations. Fix missing roles. + + * tests/annotations/docs/tester-docs.xml: + * tests/annotations/src/tester.c: + * tests/annotations/src/tester.h: + * tests/bugs/docs/tester-sections.txt: + * tests/gobject/docs/tester-docs.xml: + Update new syntax. + +2008-10-11 Stefan Kost + + * configure.in: + * tests/Makefile.am: + * tests/annotations.sh: + * tests/annotations/Makefile.am: + * tests/annotations/docs/Makefile.am: + * tests/annotations/docs/tester-docs.xml: + * tests/annotations/docs/tester-sections.txt: + * tests/annotations/src/Makefile.am: + * tests/annotations/src/tester.c: + * tests/annotations/src/tester.h: + Add testcases for gir annotation. + +2008-10-03 Stefan Kost + + patch by: Matthew Barnes + + * gtkdoc-scan.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.h: + Be more careful with "struct _". Fixes #554833. + +2008-10-03 Stefan Kost + + patch by: Behdad Esfahbod + + * gtk-doc.make: + * gtk-doc.notmpl.make: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Add rules to create $(REPORT_FILES). Fixes #552822. + +2008-10-03 Stefan Kost + + patch by: Simon Josefsson + + * examples/Makefile.am: + * tests/bugs/docs/Makefile.am: + * tests/gobject/docs-tmpl/Makefile.am: + * tests/gobject/docs/Makefile.am: + Use GTKDOC_CFLAGS instead of INCLUDES in Makefile.am. Fixes #553407. + +2008-09-24 Stefan Kost + + * gtkdoc-mkdb.in: + Use full symbol, if it does not belong to the namespace. + +2008-09-22 Stefan Kost + + * tests/gobject/src/gobject.h: + Document some odd behaviour. + +2008-09-22 Stefan Kost + + * TODO: + More todos. + + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: + * tests/bugs/src/tester.h: + Add testcase for bug 552602. + + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Also use new RUN envvar here. + +2008-09-10 Stefan Kost + + * gtkdoc-mkdb.in: + Generate unique ids for properties, style and child properties. + + * gtk-doc.make: + * gtk-doc.notmpl.make: + * gtkdoc-scan.in: + * gtkdoc-scangobj.in: + If we use libtool, run scanner under libtool to use uninstalled + libraries. + +2008-09-04 Stefan Kost + + * gtkdoc-mkhtml.in: + Fix comparison. + + * TODO: + ideas. + + * configure.in: + * gtk-doc-fo.xsl: + * gtk-doc.xsl: + * gtkdoc-common.pl.in: + * gtkdoc-mkdb.in: + * help/manual/C/gtk-doc-manual.xml: + * tests/bugs/docs/Makefile.am: + * tests/bugs/docs/tester-docs.xml: + * tests/gobject/docs-tmpl/Makefile.am: + * tests/gobject/docs-tmpl/tester-docs.xml: + * tests/gobject/docs/Makefile.am: + * tests/gobject/docs/tester-docs.xml: + * tests/gobject/src/gobject.h: + Switch to docbook 4.3 dtd. Fixes #487727. + Add --name-space option to gtkdoc-mkdb for nicer indexes. Start with a + fo wrapper for pdf output. + +2008-09-04 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Don't install index.sgml twice. Also remove the " || :;" construct + that ssems to be there only to eat the return code. + +2008-07-23 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-scan.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.h: + Accept "char const *" as well. Fixes #544172. + +2008-07-21 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Only specify options if gtkdoc-mkhtml can take them. Fixes #543855. + + * gtkdoc-mkhtml.in: + Don't use bash specific features. Be more flexible so that we can add + more options. + +2008-07-09 Stefan Kost + + * gtkdoc-scan.in: + Fix struct/enum level parsing which could go one to high and then the + main struct would never be closed. + Fixes #542137 + +2008-06-28 Stefan Kost + + * autogen.sh: + Mention why this change is bad. + +2008-06-28 Stefan Kost + + patch by: David Nečas + + * examples/Makefile.am: + * gtk-doc.make: + * gtk-doc.notmpl.make: + * gtkdoc-mkhtml.in: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Add searchpath to gtkdoc.mkhtml. Fixes #460753 + +2008-06-22 Stefan Kost + + * autogen.sh: + To support timj aclocal setup we are shipping gnome-doc-utils.m4 + and making sure automake picks it up ;) + +2008-06-22 Stefan Kost + + * tools/migratetmpl.pl: + We were still removing too many s. + Also add andrews trick to escape the c comments. + Add a newline to empty param docs. + +2008-06-22 Stefan Kost + + * m4/gnome-doc-utils.m4: + Add this to svn, so that bootstrap work where no gnome-doc-utils is + available yet. + +2008-06-21 Stefan Kost + + * tools/migratetmpl.pl: + Factor out multiline formatting and use for deprecated field too. + +2008-06-21 Stefan Kost + + * gtkdoc-mkdb.in: + Commenting. + + * tools/migratetmpl.pl: + Convert character entities back. + +2008-06-21 Stefan Kost + + * TODO: + Start collection info about slowly deprecating crack. + + * tools/migratetmpl.pl: + Add title. + +2008-06-21 Stefan Kost + + * tools/migratetmpl.pl: + Use $file in section comment not title. Convert only standalone para + tags. + +2008-06-21 Stefan Kost + + * tools/migratetmpl.pl: + Convert @Varargs: to @...: + +2008-06-21 Stefan Kost + + * tools/migratetmpl.pl: + Convert single line c comments to c++ ones. Indent multiline parameter docs. + +2008-06-16 Stefan Kost + + * gtkdoc-mktmpl.in: + Don't reuse file var, fixes warning context. + + * gtkdoc-scan.in: + Also accept *.hh as headers suffix. + +2008-06-10 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Include original CFLAGS / LDFLAGS when building the scanner. Allows to + have own FLAGS defined in addition. + +2008-06-08 Stefan Kost + + * TODO: + More planning. + +2008-06-08 Stefan Kost + + * TODO: + Add more ideas. + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + Merge two fwrite calls. + + * tests/gobject/examples/gobject.c: + * tests/gobject/src/gobject.c: + Demonstrate how to include source fragments from external files. + + * tests/gobject/src/giface.h: + * tests/gobject/src/gobject.h: + Documents two entries. + +2008-06-07 Sebastian Dröge + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + Add "%s" format strings to printf-like functions when printing + a string. Fixes #536980. + +2008-06-05 Stefan Kost + + * gtkdoc-fixxref.in: + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Fix quoting. + + * tools/migratetmpl.pl: + Add first version of a tool to support migration from tmpl docs to + source code comments. + +2008-06-04 Stefan Kost + + * autogen.sh: + Correct invocation for gnome-doc-prepare. + +2008-06-04 Stefan Kost + + * gtkdoc-common.pl.in: + Handle file or line being undefined. + + * gtkdoc-mkdb.in: + Warn about repeated symbols in sections. Also give line of previous + occurrence. Also give that info for double file entries. Fixes #473342 + Give correct error locate for one warning. Fixes #532395 partially + +2008-06-04 Stefan Kost + + * gtkdoc-mkdb.in: + Don't warn about overridden docs comment if its the same text. + +2008-06-03 Stefan Kost + + * TODO: + Spelling. + + * gtkdoc-mkdb.in: + Warn and skip double file entries in section files. + + * gtkdoc-mktmpl.in: + Use the new warning format in this script too. + + * gtkdoc-rebase.in: + Also use optional parameters here. + +2008-06-02 Stefan Kost + + * tests/gobject/docs-tmpl/tester-docs.xml: + * tests/gobject/docs-tmpl/tester-sections.txt: + * tests/gobject/docs/tester-docs.xml: + * tests/gobject/docs/tester-sections.txt: + * tests/gobject/src/giface.c: + * tests/gobject/src/gobject.c: + * tests/gobject/src/gobject.h: + Add some since: tags for the tests too. + +2008-06-02 Stefan Kost + + * TODO: + tody up and add some comments regarding HTML_DIR. + + * gtkdoc-fixxref.in: + HTML_DIR is not necessarily set. + + * gtkdoc-mkhtml.in: + Fix uninstalled. + + * tests/gobject/docs-tmpl/tester-docs.xml: + * tests/gobject/docs/tester-docs.xml: + Add more chapter id's and experiment with an index chapter. + +2008-06-02 Stefan Kost + + * style.css: + Improve spacing on indices and glossaries. + +2008-06-02 Stefan Kost + + * TODO: + * tests/bugs/docs/tester-docs.xml: + * tests/gobject/docs/tester-docs.xml: + * tests/gobject/docs/tester-sections.txt: + * tests/gobject/docs-tmpl/tester-docs.xml: + * tests/gobject/docs-tmpl/tester-sections.txt: + * tests/gobject/src/gobject.c: + * tests/gobject/src/gobject.h: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Add some index lists to the tests. Add a deprecated function. + +2008-06-02 Stefan Kost + + patch by: Felix Riemann + + * gtk-doc.xsl: + * style.css: + Produce valid html. Fixes #534627. + +2008-05-23 Stefan Kost + + * configure.in: + * tests/gobject/Makefile.am: + * tests/gobject/docs-tmpl/Makefile.am: + * tests/gobject/docs-tmpl/tester-docs.xml: + * tests/gobject/docs-tmpl/tester-sections.txt: + * tests/gobject/docs-tmpl/tester.types: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Build same docs once again with old tmpl approach. + +2008-05-23 Stefan Kost + + * tests/bugs/docs/Makefile.am: + * tests/gobject/docs/Makefile.am: + * tests/gtk-doc.make: + * tests/gtk-doc.notmpl.make: + Sync names. + +2008-05-08 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Fix a long standing bug that killed spaces in tmpl files. + +2008-05-05 Stefan Kost + + * gtkdoc-mkdb.in: + Fix regexps changes from previous commit. When using /e the + replacement part has to be a perl snippet. + +2008-05-05 Stefan Kost + + * gtkdoc-mkdb.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.h: + Don't expand '#' in ulink tags. Also allow to escape "#%@" with '\'. + Add to testsuite. Fixes #530758 + +2008-05-05 Stefan Kost + + * gtkdoc-mktmpl.in: + It is GObject not GtkObject anymore + +2008-05-05 Stefan Kost + + * TODO: + Make note about expanding urls. + + * help/manual/C/gtk-doc-manual.xml: + Document the use of |[ ]| as a shortcut for program listing. + + * tests/gobject/src/giface.h: + * tests/gobject/src/gobject.c: + Fix one undocumented symbol and add an exampl of the programlisting + shortcut. + +2008-04-22 Stefan Kost + + * HACKING: + We need to update the webpage. + + * TODO: + * configure.in: + Planning. + + * gtkdoc-mkdb.in: + Hopefully now unbreak the docbuild, if one has template but not uses + them. + +2008-04-17 Stefan Kost + + * gtkdoc-mkdb.in: + Add one more warning. Also trac location of section docs. Merge + source symbols once and then on demand (if we read a template). + +2008-04-11 Stefan Kost + + * TODO: + * configure.in: + Idea about the tracing. Not that practical as it is. + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Unify file-error messages. Improve warning detail. Fix undocumented + status for template less runs. + +2008-04-10 Stefan Kost + + * TODO: + Ideas. + + * gtkdoc-common.pl.in: + Add common method for prining (gcc-style) warnings. + + * gtkdoc-mkdb.in: + Use new method. Harmonize the warnings a bit. Remember locations + symbols are taken from template files for use in warnings. + +2008-04-09 Stefan Kost + + * HACKING: + Some releasing info. + + * gtkdoc-mkdb.in: + Print file/line number in warning. + + * help/manual/C/gtk-doc-manual.xml: + Some docs for what the -overrides.txt file is for. + +2008-03-23 Stefan Kost + + * autogen.sh: + Tell automake to not warn us about portabillity issues. Its too late + for that. + + * ChangeLog: + Surgery for the bugnumber. + +2008-03-21 Marc-Andre Lureau + + * .svnignore, Makefile.am, autogen.sh, configure.in, + help/manual/.svnignore, help/manual/C/ChangeLog, + help/manual/C/Makefile.am, help/manual/C/gtk-doc-manual-C.omf.in, + help/manual/C/gtk-doc-manual.xml, help/manual/ChangeLog, + help/manual/Makefile.am, help/manual/gtk-doc-manual.omf.in, + m4/.svnignore, omf.make, xmldocs.make: + GNOME doc-utils migration. Fixes #335239 + +2008-03-22 Stefan Kost + + * HACKING: + * configure.in: + * help/manual/C/gtk-doc-manual.xml: + Back to development. + +=== Release 1.10 === + +2008-03-19 Stefan Kost + + * NEWS: + * HACKING: + Prepare for release. + + * style.css: + Add fix for footnote positions. + +2008-02-27 Stefan Kost + + patch by: Carlos Garnacho + + * tools/gtk-doc.el: + Update emacs mode to work with emacs22. Fixes #513318. + +2008-02-01 Stefan Kost + + * gtkdoc-common.pl.in: + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + * tests/bugs/src/tester.h: + Improve tmpl parsing and add some more logging. Fixes #512154. + +2008-01-30 Stefan Kost + + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.h: + Add testcase for #512154. + +2008-01-28 Stefan Kost + + * gtkdoc-mkdb.in: + Condense all the multiple newlines in the generated xml. + + * tests/gtk-doc.make: + Make sure the testsuite call the uninstalled scripts. + +2008-01-24 Stefan Kost + + * gtk-doc.xsl: + Unbreak fixxref. The index.sgml file should not have leading + whitespace. These were caused by indenting the xsl, which is dangerous + in case of . + + * gtkdoc-fixxref.in: + Debug logging. + +2008-01-21 Stefan Kost + + * gtkdoc-common.pl.in: + Don't warn when parsing enum struct members. + +2008-01-21 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Give file and line number when complaining about duplicate + definitions. Seems to not have been applied with older commit. + + * gtkdoc-scan.in: + * tests/gobject/src/gobject.h: + Handle typedef enums. + +2008-01-17 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Don't fail in dist when no .types file is present. Fixes #509539. + +2008-01-16 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Give file and line number when complaining about duplicate + definitions. + +2008-01-14 Stefan Kost + + patch by: Joe Marcus Clarke + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Do not abort the build, if gtk-doc is not installed. Fixes #508897 + +2007-12-20 Mathias Hasselmann + + * configure.in: + Lower Python dependency to 2.3 (#503054). Just warn when Python + wasn't found. Print a configuration summary before leaving the + configure script. + * Makefile.am: + Do not install gtkdoc-depscan when Python wasn't found. + +2007-12-20 Mathias Hasselmann + + * gtkdoc-depscan.in: + Use old and/or pattern instead of the new ternary operator. + This drops the Python 2.5 dependency for that script. + Original patch by Frederic Peters. (#503054) + +2007-12-17 Mathias Hasselmann + + * configure.in: + Use AM_PATH_PYTHON instead of AC_PATH_PROG to find Python. + (#503710) + +2007-12-17 Stefan Kost + + * gtk-doc.xsl: + Render accronyms from docbook and glossary in html. + +2007-12-17 Stefan Kost + + * tests/bugs/docs/tester-docs.sgml: + * tests/bugs/docs/tester-docs.xml: + * tests/gobject/docs/tester-docs.sgml: + * tests/gobject/docs/tester-docs.xml: + Add the xml instead of the sgml docs. + +2007-12-12 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Revert last change and reopen #503119. Needs a different fix. + +2007-12-12 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Use content_files as a dependency the sgml-build.stamp. + +2007-12-11 Mathias Hasselmann + + * gtkdoc-depscan.in: + Use colon as name-version-separator in book names. + +2007-12-11 Mathias Hasselmann + + * gtkdoc-depscan.in: + Also scan devhelp folders. + +2007-12-11 Mathias Hasselmann + + * gtkdoc-depscan.in: + Print reasonable error message when passing + non-existant files on command line. + +2007-12-11 Stefan Kost + + patch by: Kouhei Sutou + + * gtk-doc.xsl: + Consistently use UTF-8 instead of US-ASCII for output encoding. + Fixes #497367 + +2007-12-10 Mathias Hasselmann + + * configure.in: + * gtkdoc-depscan.in: + * Makefile.am: + Add gtkdoc-depscan, which resolves source code dependencies + by scanning devhelp2 books. + +2007-12-10 Stefan Kost + + * devhelp2.xsd: + Update schema. + + * gtk-doc.notmpl.make: + Remove left-over 'fi'. + +2007-12-05 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Better fix for #501066. + +2007-12-05 Stefan Kost + + * devhelp2.xsd: + Add first version of the schema. + + * devhelp2.xsl: + Unbreak the devhelp2 file generation. + + * tests/gtkdoctest.sh: + Add comment about doing schmea checks once they work. + +2007-12-04 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Apply build flags cleanups from #498521. Spotted by + dmacks@netspace.org. + +2007-12-04 Stefan Kost + + * tests/gobject/src/giface.c: + * tests/gobject/src/gobject.c: + Uhm, unbreak the links in the test docs. + +2007-12-04 Stefan Kost + + * tests/gobject/src/giface.c: + * tests/gobject/src/gobject.c: + Little test cleanup. The bug was already fixed. + +2007-12-04 Stefan Kost + + * tests/gobject/docs/tester-sections.txt: + * tests/gobject/docs/tester.types: + * tests/gobject/src/Makefile.am: + * tests/gobject/src/giface.c: + * tests/gobject/src/giface.h: + * tests/gobject/src/gobject.c: + * tests/gobject/src/gobject.h: + * tests/gobject/src/tester.c: + * tests/gobject/src/tester.h: + Refactor tests for #489279. + +2007-12-04 Stefan Kost + + * gtkdoc-common.pl.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.h: + Add testcase for #501038. Improve struct parsing to correctly finish + if the last line in struct declaration was a preprocessor statement. + Fixes #501038. + +2007-12-04 Stefan Kost + + patch by: David Nečas + + * gtkdoc-common.pl.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: + * tests/bugs/src/tester.h: + Handle forward typedef'd enums. Fixes #446648. + +2007-12-02 Loïc Minier + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Add double-quotes around `which gtkdoc-rebase` to prevent "test" + from failing with "/bin/sh: line 11: test: !=: unary operator + expected ". Fixes #501066. + +2007-11-11 Stefan Kost + + patch by: David Nečas + + * gtk-doc.xsl: + * gtkdoc-mkdb.in: + Avoid generated node ids. Fixes #365913. + +2007-11-11 Stefan Kost + + * gtk-doc.xsl: + * gtkdoc-mkdb.in: + * style.css: + Alternative and cleaner footer implementation (unblock #365913). + +2007-11-11 Stefan Kost + + patch by: David Nečas + + * gtkdoc-mkdb.in: + * gtkdoc-scangobj.in: + Display proper types for pointer properties. Fixes #468278. + +2007-10-31 Stefan Kost + + * gtkdoc-mkdb.in: + Only warn about missing deprecation guards for declared symbols. + Fixes #492005. + +2007-10-31 Stefan Kost + + * tests/gtk-doc.make: + * tests/gtkdoctest.sh: + Run our own check script. Clean the make output a bit. + +2007-10-31 Stefan Kost + + * help/manual/C/gtk-doc-manual.xml: + Small doc fix. + +2007-10-31 Stefan Kost + + * Makefile.am: + Formatting. + + * configure.in: + * tests/gtk-doc.make: + Cleanup the 'make check' deps configure check. + +2007-10-01 Stefan Kost + + * configure.in: + * help/manual/C/gtk-doc-manual.xml: + Back to development. + +=== Release 1.9 === + +2007-09-30 Stefan Kost + + * NEWS: + Releasing 1.9. + +2007-09-27 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + * gtkdoc-rebase.in: + New day, new fix. Remove testing $(DESTDIR) from makefile and use + Getopt::Long qw(:config gnu_getopt); in rebase. + +2007-09-26 Stefan Kost + + * gtk-doc.make: + And actually saving before committing might greatly help. + +2007-09-26 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Another attempt to fix the rules. + +2007-09-26 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + If there is nothing to install, don't rebase. + +2007-09-26 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Unbreak the last change. + +2007-09-26 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Handle DESTDIR= case. + +2007-09-26 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + * gtkdoc-rebase.in: + Fix destdir option name. + +2007-09-25 Stefan Kost + + * tests/gtk-doc.make: + Get make distcheck fully working. + +2007-09-25 Stefan Kost + + * tests/Makefile.am: + * tests/bugs.sh: + * tests/gobject.sh: + * tests/gtkdoctest.sh: + Try to get make distcheck to run. + + * tests/gtk-doc.make: + Don't dist docs generated during test runs and remove some cruft. + + +2007-09-24 Stefan Kost + + patch by: David Nečas + + * NEWS: + * tests/bugs/docs/Makefile.am: + * tests/gobject/docs/Makefile.am: + * tests/gtk-doc.make: + Adapt xml/ cleaning from gtk-doc.notmpl.make. Clean log files. + +2007-09-24 Stefan Kost + + * NEWS: + Current release notes. + +2007-09-24 Stefan Kost + + * MAINTAINERS: + Make mango happy. + + * examples/Makefile.am: + * gtk-doc.make: + * gtk-doc.notmpl.make: + Process files from DISTCLEANFILES in the dist-hooks. + +2007-09-24 Stefan Kost + + patch by: David Nečas + + * Makefile.am: + Add gtk-doc.notmpl.make to EXTRA_DIST. Fixes #479913. + +2007-09-20 Stefan Kost + + * gtkdoc-fixxref.in: + Revert online option for fixxref now that we have a rebase command. + +2007-09-18 Stefan Kost + + * gtkdoc-scan.in: + Handle function pointers. Fixes #477532. + +2007-09-18 Stefan Kost + + patch by: David Nečas + + * gtkdoc-scan.in: + Parse reoccuring const. Fixes #471014. + + * tests/bugs/docs/Makefile.am: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: + * tests/bugs/src/tester.h: + * tests/gobject/docs/Makefile.am: + * tests/gobject/src/tester.c: + * tests/gobject/src/tester.h: + Add more tests and cleanup the test-code a little. + +2007-09-17 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Revert some Makefile improvements, as we can't control the quoting + reliably. + +2007-09-11 Stefan Kost + + * gtkdoc-mkdb.in: + Default master doc should have proper extension. Fixes #467773. + +2007-09-11 Stefan Kost + + patch by: David Nečas + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Makefile improvements. + +2007-09-03 Stefan Kost + + * MAINTAINERS: + Update MAINTAINER to adhere to rules given on + http://live.gnome.org/MaintainersCorner#maintainers + +2007-08-23 Benjamin Otte + + * gtkdoc-mktmpl.in: + sync with gtkdoc-mkdb completely. Really fixes #419997 + +2007-08-21 Stefan Kost + + * gtkdoc-mkdb.in: + * style.css: + Add divider and empty space at the bottom. Mostly fixes #448879. + +2007-08-21 Stefan Kost + + * gtk-doc.make: + * gtk-doc.notmpl.make: + Make use of rebase if possible. Fixes #465920 + + * gtkdoc-rebase.in: + Rebase improvements and fixes. + +2007-08-16 Stefan Kost + + * .cvsignore: + * help/.cvsignore: + * help/manual/.cvsignore: + * help/manual/C/.cvsignore: + Get rid of cvsignore files. + +2007-08-14 Stefan Kost + + * gtkdoc-common.pl.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.h: + Don't die when encountering #if/#endif in enums. Fixes #324535. + +2007-08-14 Stefan Kost + + patch by: Frederic Peters + + * style.css: + Styling hr tags. + +2007-08-14 Stefan Kost + + * help/manual/C/gtk-doc-manual.xml: + Document new features and bump version. + +2007-08-13 Stefan Kost + + * gtkdoc-mkdb.in: + Fix the funny side-effect of last 'broken-returns' fix. + +2007-08-13 Stefan Kost + + * gtkdoc-scan.in: + * tests/bugs/src/tester.h: + Really fix #460127. + +2007-08-13 Stefan Kost + + * gtkdoc-mkdb.in: + Now the 'broken' returns seems to work better. Fixes #380824 more. + +2007-08-13 Stefan Kost + + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c (bug_379466, bug_380824): + * tests/bugs/src/tester.h (test): + New test. + * tests/gtkdoctest.sh: + Fix bashism. + +2007-08-12 Stefan Kost + + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.h: + Add another test for a bug we fixed with the changes below. + Fixes #460127. + +2007-08-12 Stefan Kost + + * gtkdoc-scan.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: + * tests/bugs/src/tester.h: + Improved scan logic. Fixes #411739. + +2007-08-12 Stefan Kost + + * gtkdoc-mkdb.in: + * tests/bugs/src/tester.h: + Handle newline in declarations better. Fixes #379466. + Ensure space in multiline declarations when removing the newline. + Fix missing argument docs in template free build. + +2007-08-12 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Handle "unsigned long|unsigned short|signed long|signed short". + Fixes #445693. + +2007-08-12 Stefan Kost + + * Makefile.am: + * configure.in: + * gtkdoc-check: + * gtkdoc-check.in: + Replacing my shell based test script by Davids perl based one. Add + licence, copyright and docs header. Integrate with build. + +2007-08-12 Stefan Kost + + patch by: David Nečas + + * gtkdoc-scangobj.in: + Make introspection of interfaces work in more cases. Fixes #355352. + +2007-08-12 Stefan Kost + + patch by: David Nečas + + * configure.in: + Cleanup glib detection for tests. + +2007-08-11 Stefan Kost + + * gtkdoc-check: + Fix modulename check. + +2007-08-11 Stefan Kost + + * Makefile.am: + Install new makefile. + + * configure.in: + Bump version as we're working on 1.9. + + * gtkdocize.in: + Add option to select makefile-flavour. + +2007-08-11 Stefan Kost + + * gtk-doc.make: + Add dummy rule to make first build run through. Fixes #156643 + +2007-08-11 Stefan Kost + + * style.css: + Hide fixed navigationbar when printing. Fixes #449618 + +2007-08-11 Stefan Kost + + * gtk-doc.notmpl.make: + Add new makefile for tmpl-less build. + +2007-08-11 Stefan Kost + + patch by: David Nečas + + * autogen.sh: + Accepts automake 1.10 too. Fixes #459225 + +2007-08-11 Stefan Kost + + * gtkdoc-mkdb.in: + Make the tmpl-less build work. + + * tests/gtk-doc.make: + Switch again to the tmpl-less build. + +2007-08-10 Stefan Kost + + patch by: Rouslan Solomakhin + + * configure.in: + Fix the build. + +2007-08-10 Stefan Kost + + * gtk-doc.make: + * tests/gtk-doc.make: + Revert fix for #433338 and reopen bug. Breaks if file is not there, + e.g. if --rebuild-types is used. + +2007-08-10 Stefan Kost + + * gtk-doc.make: + Some cleanups. + + * tests/gtk-doc.make: + Try the tmpl free build here. + +2007-08-10 Stefan Kost + + * examples/Makefile.am: + Add commented out TESTS. + + * gtk-doc.m4: + Check for location of gtkdoc-check. + + * Makefile.am: + * gtkdoc-check: + Test doc status and print result in check like layout. + +2007-08-02 Stefan Kost + + patch by: Sven Herzberg + + * gtk-doc.make: + * tests/gtk-doc.make: + Rebuild documentation of $(DOC_MODULE).types changed. Fixes #433338 + +2007-08-02 Stefan Kost + + patch by: David Nečas + + * Makefile.am: + * configure.in: + * gtkdoc-rebase.in: + Allow rebasing cross-references in generated docs. Fixes #434134. + +2007-08-02 Stefan Kost + + * gtkdoc-mkhtml.in: + Add a hack to gtkdoc-mkhtml to run uninstalled too. + +2007-08-02 Stefan Kost + + Patch by: David Nečas + + * gtk-doc.xsl: + Generate ONLINE tag in index.sgml. + + * gtkdoc-fixxref.in: + Allow to base links against online versions of xreffed docs. + Fixes #454916. + + * gtkdoc-mkdb.in: + Add releaseinfo to doctemplates. + + * tests/bugs/docs/tester-docs.sgml: + * tests/gobject/docs/tester-docs.sgml: + Update templates. + +2007-08-02 Stefan Kost + + * tests/bugs/docs/Makefile.am: + * tests/gobject/docs/Makefile.am: + * tests/gtk-doc.make: + Use PERL5LIB envvar to use uninstalled gtkdoc-common.pl for tests. + Use tee to both show and redirect logs. + Build test-docs in check-local instead of all-local. + Fixes #459725. + +2007-07-25 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-scan.in: + Some more debug prints and code cleaning. + +2007-07-23 Stefan Kost + + Patch by: Yeti + + * gtk-doc.make: + * gtkdoc-mkdb.in: + Report undeclared symbols into a file. Fixes #436565. + +2007-07-18 Stefan Kost + + * gtkdoc-mkdb.in: + Readd two debug prints and remove one obsolete one. + + * tests/bugs/Makefile.am: + * tests/gobject/Makefile.am: + Enforce 'make clean' before 'make check'. + +2007-07-18 Stefan Kost + + Patch by: Yeti + + * gtkdoc-mkdb.in: + Cleanup broek-return handling and add ignore_broken_returns for + section docs. Fixes #457077 + + * tests/bugs/docs/Makefile.in: + * tests/gobject/docs/Makefile.in: + Remove. + + * tests/gtk-doc.make: + Use the local tools so that 'make check' works uninstalled. + + +2007-07-18 Stefan Kost + + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: (bug_419997): + * tests/bugs/src/tester.h: + * tests/gobject/src/tester.c: (gtkdoc_tester_class_init): + * tests/gobject/src/tester.h: + Add more test cases. + +2007-07-17 Stefan Kost + + * tests/bugs/docs/Makefile.in: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/src/tester.c: (bug_141869_a), (bug_141869_b), + (bug_379466), (bug_445693): + * tests/bugs/src/tester.h: + * tests/gtk-doc.make: + * tests/gtkdoctest.sh: + Improve test suite. + +2007-07-17 Stefan Kost + + Patch by: Yeti + + * gtkdoc-common.pl.in: + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + * gtkdoc-scan.in: + Improve paramenter parsing to allow parameter names that contain + const or restricted. Fixes #419997 + Also fix the signed/unsigned more. + +2007-07-17 Stefan Kost + + * Makefile.am: + * autogen.sh: + * configure.in: + * tests/Makefile.am: + * tests/bugs.sh: + * tests/bugs/Makefile.am: + * tests/bugs/docs/Makefile.am: + * tests/bugs/docs/Makefile.in: + * tests/bugs/docs/tester-docs.sgml: + * tests/bugs/docs/tester-sections.txt: + * tests/bugs/docs/tester.types: + * tests/bugs/src/Makefile.am: + * tests/bugs/src/tester.c: (bug_445693), (bug_141869_a), + (bug_141869_b): + * tests/bugs/src/tester.h: + * tests/gobject.sh: + * tests/gobject/Makefile.am: + * tests/gobject/docs/Makefile.am: + * tests/gobject/docs/Makefile.in: + * tests/gobject/docs/tester-docs.sgml: + * tests/gobject/docs/tester-sections.txt: + * tests/gobject/docs/tester.types: + * tests/gobject/src/Makefile.am: + * tests/gobject/src/tester.c: (gtkdoc_tester_new), + (gtkdoc_tester_get_property), (gtkdoc_tester_set_property), + (gtkdoc_tester_class_init), (gtkdoc_tester_get_type): + * tests/gobject/src/tester.h: + * tests/gtk-doc.make: + * tests/gtkdoctest.sh: + Add test-suite. Fixes #457173 + +2007-07-16 Stefan Kost + + Patch by: Yeti + + * gtkdoc-mkdb.in: + Avoid useless $return_start access. + +2007-07-16 Stefan Kost + + Patch by: Petteri Räty + + * gtk-doc.m4: + Make gtk-doc.m4 fail when needed gtk-doc is not installed and notify + user. Fixes #323938 and #450338. + +2007-07-15 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Handle signed/unsigned without int. Fixes #141869. + +2007-07-15 Stefan Kost + + Patch by: Yeti + + * gtkdoc-mkdb.in: + Improve handling of legacy "return" statement doc parsing. Warn about + those. + +2007-07-15 Stefan Kost + + * gtkdoc-mkdb.in: + Fix perl warning about usage of undefined symbol. + +2007-07-15 Stefan Kost + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + Sync the function decl arg parsing. Fixes #419308. + +2007-07-15 Stefan Kost + + * gtkdoc-fixxref.in: + Improve the ---help output a little. + +2007-07-15 Stefan Kost + + * gtkdoc-fixxref.in: + Improve detection of absolute/relatives paths. Skip duplicate paths. + Fixes #453717. + +2007-06-14 Lo�c Minier + + * gtk-doc.make: + Cleanup $(DOC_MODULE)-undocumented.txt files in + maintainer-clean-local. Fixes #415388. + +2007-06-14 Lo�c Minier + + * gtk-doc.m4: + Fix warnings in m4 macros when running "autoreconf -fi -Wall"; + Guillem Jover. Fixes #428596. + +2007-06-11 Damon Chaplin + + * gtkdoc-mkdb.in (ExpandAbbreviations): just output "signal" and + "property" as the text for cross-reference links to signals and + properties, rather than something like "Object::signal" which can get + a bit long. Also tidied up the code a little. + (GetArgs): put the " inside the literal element. + (GetSignals): use a literal element for the signal name in the title, + to match the properties. + +2007-03-16 Stefan Kost + + * gtkdoc-common.pl.in: handle preprocessor statements in enum and + struct declarations. Fixes #418027. + +2007-02-27 Stefan Kost + + * gtk-doc.xsl: create toc for part and reference + + * style.css: Fix placement of div.reference + +=== release 1.8 === + +2007-02-16 Damon Chaplin + + * Released 1.8. + +2007-02-16 Damon Chaplin + + * gtkdoc-scan.in: only rebuild the .types file automatically on the + very first run (i.e. when there are no sections or types files). + + * gtkdoc-scangobj.in: skip gnome_keyring_item_info_get_type if it is + in the .types file as it isn't a real GObject type. This is a hack to + avoid breaking the GNOME build. See bug #386508. + +2007-02-11 Stefan Kost + + * gtk-doc.xsl: fix prerequisite section in nav-header + +2007-02-07 Stefan Kost + + * style.css: fixing footnote subscripts, make tables look nicer. + #405051 + +2007-02-07 Damon Chaplin + + * gtk-doc.make: make $(DOC_MODULE)-sections.txt and + $(DOC_MODULE)-overrides.txt depend on scan-build.stamp, so that + parallel make works. #404122, Ed Catmur. + +2007-02-07 Damon Chaplin + + * gtkdoc-scangobj.in: don't return if !G_TYPE_IS_OBJECT (object_type) + as that means interface properties don't get output. This was broken + by the patch for #348058. + +2007-01-21 Damon Chaplin + + * gtkdoc-mkdb.in: added "--default-includes" option to specify the + default "#include"s to place at the top of the synopsis of each + section. Normally this is specified in a ... line + in MODULE-sections.txt, but if you are using the "--rebuild-sections" + option to automatically rebuild the MODULE-sections.txt file you can't + use that. #395023. + +2007-01-21 Damon Chaplin + + * gtkdoc-mktmpl.in (ReadTemplateFile): + * gtkdoc-mkdb.in (ReadTemplateFile): improved param regexp to handle + weird macro vararg names like "format...". #398971. + +2007-01-16 Damon Chaplin + + * gtkdoc-mkdb.in: support "Include" setting in section docs in source + code, same as ... setting in sections.txt file. + Part of #395023. + +2007-01-16 Damon Chaplin + + * gtkdoc-mkdb.in (OutputMacro): try to line up multiple lines of + arguments if possible. #384249 + +2007-01-16 Damon Chaplin + + * gtkdoc-scan.in (ScanHeader): for headers marked private, return + immediately so we don't add anything to the sections file. #395005. + +2007-01-16 Damon Chaplin + + * gtkdoc-mkdb.in: a number of changes to help when adding example code + to the docs (#368382): + + a) Support CDATA in source code comments. (We don't touch anything in + CDATA.) + b) Support |[ ... ]| to include example code. (Just gets converted to + ) + c) Improve handling, by not inserting + and not expanding "()", "@" or "%". (It still expands '#' so people + can use cross-references to any symbols if they want to.). + d) Improve '#' links a bit by skipping symbols that look like C + preprocessor directives (e.g. "#include"). + e) Improve '&' handling a bit by converting to '&' if it doesn't + already look like the start of an entity reference. + f) Added special case for "#include " in so the + "<" and ">" get replaced by entities. + + * gtkdoc-mktmpl.in (ReadTemplateFile): + * gtkdoc-mkdb.in (ReadTemplateFile): fixed param regexp so it handles + "@...:" for varargs again. It also cleans up messed up template files + luckily. + +2007-01-04 Damon Chaplin + + * gtk-doc.make (dist-hook): abort dist if html docs aren't generated. + #166462, Gustavo Carneiro. + +2007-01-03 Damon Chaplin + + * gtkdoc-mkdb.in: improved output a little - made field widths larger, + removed signal prototypes from synopsis, and capitalized all signal + flags (to be consistent with argument capitalization). #384247, + Hans Petter Jansson. + +2007-01-03 Damon Chaplin + + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-mkdb.in (OutputFunction): fix parsing of "char * const" + arguments, with an extra "\s*". #387681 + +2007-01-03 Damon Chaplin + + * omf.make: + * xmldocs.make: updated to new versions from gnome-common. #363622 + Also reverted the changes made for #316508 since they may cause + problems. We'll let the scrollkeeper/gnome-common/autoconf people + sort out that issue. + +2006-12-07 Ross Burton + + * help/manual/C/gtk-doc-manual.xml: + Add examples of how to document structs, properties and signals + (#383401). + +2006-12-04 Damon Chaplin + + * gtkdoc-scangobj.in: added a '--query-child-properties' argument to + allow you to specify a function to return a list of child properties + for a class (similar to GtkContainer child properties). #379203 + +2006-10-16 Damon Chaplin + + * gtkdoc-scangobj.in: remove a shadow declaration to avoid compiler + warnings. #362475 + +2006-10-15 Damon Chaplin + + * gtkdoc-scan.in: added a '--rebuild-sections' option that will + automatically recreate the MODULE-sections.txt file each time. + (This only works for projects with very neat header files.) #310494. + +2006-10-15 Damon Chaplin + + Bug #338517: Automatically creating/updating .types file: + + * gtkdoc-scan.in: added a '--rebuild-types' option which will + automatically update the .types file using all _get_type() functions + found in the headers. (It will also do this if no .types file is found, + i.e. when gtk-doc is first run on a project.) + + * gtk-doc.make (scan-build.stamp): run gtkdoc-scan before + gtkdoc-scangobj so we can use the generated .types file. + + * gtkdoc-scangobj.in: if the .types file doesn't have any #include + directives, just output "extern GType *get_type();" declarations for + each *_get_type() function. + +2006-10-14 Damon Chaplin + + * gtkdoc-mkdb.in (ExpandAbbreviationsExceptCDATA): new function used + to expand abbreviations in extra files, but leaving CDATA sections + as they are. (#360579) + +2006-10-14 Damon Chaplin + + * gtkdoc-mkdb.in (OutputSGML): Allow the section id to be set from + within the source code "SECTION:" comment block. (#349855) + +2006-10-13 Damon Chaplin + + * style.css: added missing comma from previous fix (#360967). + +2006-10-13 Damon Chaplin + + * gtkdoc-mkdb.in (OutputSymbolTraits): new function to output the + "Since" and "Stability Level:" paragraphs, with roles to allow + XSLT styling. (#348046) + +2006-10-13 Damon Chaplin + + * gtkdoc-scangobj.in: support interfaces on non-GObject types. + (#348058, Josh Parsons). + +2006-10-13 Damon Chaplin + + * gtkdoc-scangobj.in: make sure interfaces are initialized so the + signals query works. (#355352) + +2006-10-13 Damon Chaplin + + * style.css: Make sure appendix title isn't obscured by navigation bar + (#360967, Philip Kovacs). + +2006-09-09 Matthias Clasen + + * gtkdoc-scangobj.in (get_type_name): Don't set is_pointer + to TRUE for enum and flags types. (#354880, Yevgen Muntyan) + +=== release 1.7 === + +2006-07-29 Damon Chaplin + + * Released 1.7. + +2006-06-30 Damon Chaplin + + * gtkdoc-mkdb.in (ScanSourceFile): fix regexp to allow section names + with '-' in them. + + * gtk-doc.make (all-local, docs): added separate 'docs' target that can + be used even when the '--disable-gtk-doc' configure option is used. + +2006-06-15 Jody Goldberg + + * gtkdoc-mkdb.in (OutputFunction) : finish off #341872 + Support 'T const * const *foo' and other more complex types. + Support ptr2ptr2func as a func argument. + 'void foo (void (**func) (void))' + * gtkdoc-mktmpl.in : ditto. + + (committed by Damon with minor changes to spacing so GTK+ docs are + unchanged). + +2006-06-09 Damon Chaplin + + * gtkdoc-mkdb.in: + * gtk-doc.xsl: use the 'role' attribute rather than the 'id' attribute + to identify the different sections for the navigation bar, since 'id' + must be unique throughout the entire document. Also fixed a few minor + issues with the output. (#342861, Leonardo Boshell) + +2006-05-30 Damon Chaplin + + * gtkdoc-fixxref.in (FixHTMLFile): Use the 's' modifier to the + substitution so we handle links spanning more than one line. + (#342845). + +2006-05-22 Damon Chaplin + + * configure.in: + * Makefile.am: + * help/Makefile.am: + * help/manual/Makefile.am: use a separate Makefile.am for each + subdirectory rather than using "SUBDIRS=help/manual/C". + +2006-05-21 Jody Goldberg + + * gtkdoc-common.pl.in (ParseStructDeclaration) : Support + 'long double foo' and + 'T const * const *foo' (#341872) + * gtkdoc-mktmpl.in (OutputDeclaration) : handle ptrs to ptrs to + functions 'void func (void (**ptr2ptr2func)(int a))' + +2006-05-21 Damon Chaplin + + * gtkdoc-mkdb.in (ScanSourceFile): don't check basename for '.[hc]' + suffix since we allow other suffixes as well now. (#340199) + + * gtkdoc-mktmpl.in (OutputSignalTemplates): check if the parameter + is actually in the source code comment block. If not, use the default + name. Otherwise we were outputting an empty "@:" in the templates. + (ReadTemplateFile): remove empty "@:" lines caused by above bug. + +2006-04-15 Damon Chaplin + + * xmldocs.make: use gtkdochelpdir rather than docdir to avoid clash + with autoconf. (#316508) + + * tools/gtk-doc.el: Output "Returns:" rather than "Return value:", + and a "C-x4s" binding for inserting a blank section header. + + * gtk-doc.make (sgml-build.stamp): added $(DOC_MODULE)-sections.txt + to the dependencies, since although the templates depend on it, they + may not be changed, but the XML should still be rebuilt. + + * gtkdoc-mkdb.in (ScanSourceFile): allow whitespace after "SECTION:". + +2006-04-13 Damon Chaplin + + * gtkdoc-mkdb.in (ReadArgsFile): When outputting a warning about a + property, use a single colon ':', since that is what is used to + document properties in the source code. (2 colons are used for signals) + + * gtk-doc.make (sgml-build.stamp): added $(HFILE_GLOB) here, to + catch any new documentation in the headers. + +2006-04-12 Damon Chaplin + + * gtkdoc-mkdb.in (tagify2): strip special "-struct" suffix from + text of links to widget structs. + +2006-04-09 Stefan Kost + + * TODO: + fix link after live.gnome.org wiki changes + +=== release 1.6 === + +2006-04-09 Damon Chaplin + + * Released 1.6. + +2006-03-29 Stefan Kost + + * gtkdoc-scangobj.in: + missing '*' for arg in signal prototype in docs (#335486) + +2006-03-26 Damon Chaplin + + * gtkdoc-mkdb.in (MergeSourceDocumentation): don't output warnings + for overridden titles, since that happens a lot. (#320010) + + * configure.in: check for pkg-config >= 0.19. + + * Makefile.am (pkgconfigdir): put the .pc file in $(datadir) rather + than $(libdir), since gtk-doc is architecture-independant. (#120950) + + * configure.in: removed the hard dependency on openjade or jade, since + XML is used mostly now rather than SGML. We just output a warning + rather than an error if neither openjade or jade are found. + +2006-03-21 Stefan Kost + + * style.css: + add sect1 to pages with top-page offset adjustment (#166363) + +2006-03-19 Damon Chaplin + + * gtkdoc-scan.in (ScanHeader): try to handle the start of function + declarations spread over 3 lines. (#321708, Jorn Baayen) + +2006-03-19 Damon Chaplin + + (OutputOldParams): don't bother outputting unused parameters if they + don't have any documentation as that is pointless. + +2006-03-19 Damon Chaplin + + * gtkdoc-mktmpl.in (ReadTemplateFile): Add a workaround for an old + bug handling macros with arguments spread over several lines. (#318666) + +2006-03-19 Damon Chaplin + + * gtkdoc-mkdb.in (MakeIndexterms): Make sure we still output an index + term if there isn't 'deprecated' or 'since' info. + (#334851, Tommi Komulainen). + +2006-03-19 Damon Chaplin + + * gtkdoc-scan.in (ScanHeader): added "--ignore-decorators" option to + ignore a list of declarators in function declarations. + (#316512, Bertram Felgenhauer). + +2006-03-19 Damon Chaplin + + * gtkdoc-mkdb.in (GetSignals, GetArgs): call MakeIndexTerms() to make + sure that signals appear in the deprecated/new symbol indices. + (#332007, Tommi Komulainen). + +2006-03-19 Damon Chaplin + + * gtkdoc-mkdb.in (OutputEnum, ExpandAbbreviations, symbolify): + allow use of '#Object::signal' and '#Object:property' to link to + signals and properties, and add links to enum constant values. + (#332483, Stefan Kost) + +2006-03-15 Matthias Clasen + + * gtkdoc-mkdb.in (MakeIndexterms): Create separate indexterms + for different roles, since the docbook stylesheets don't handle + multiple roles in one attribute. (#331586, Tommi Komulainen) + +=== release 1.5 === + +2006-03-07 Damon Chaplin + + * Released 1.5. + +2006-03-06 Tommi Komulainen + + * gtkdoc-scan.in (ScanHeader): Print object name after in + order to get get object hierarchy, signals and properties + documentation appear automatically (#333380) + +2006-01-24 Stefan Kost <ensonic@users.sf.net> + + * gtkdoc-mkdb.in: patch from Damon Chaplin to fix signal flag parsing + +2006-01-08 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in: patch from Jonathan Blandford to add support for a + "--source-suffixes" option so you can scan files with any suffixes + you want (e.g. C++ files). + +2005-12-19 Matthias Clasen <mclasen@redhat.com> + + * gtkdoc-mktmpl.in: Use \w+: instead of \S+: when + matching parameter names, so that @Deprecated:2.10: + works in template files like in source code comments. + + * gtkdoc-mkdb.in: Add a missing "and" to the versioned + deprecation note. + +2005-12-09 Stefan Kost <ensonic@users.sf.net> + + * devhelp.xsl: + try more to downgrade devhelp for old file format + +2005-12-09 Stefan Kost <ensonic@users.sf.net> + + * Makefile.am: + add devhelp2 files + * autogen.sh: + create a autoregen.sh + * devhelp.xsl: + * devhelp2.xsl: + * gtk-doc.xsl: + generate two separate versions + * gtkdoc-mkdb.in: + fix parsing const after type (#322556) + * gtkdoc-mktmpl.in: + fix parsing multiline macro heads (#320588) + * gtkdoc-scangobj.in: + allow additional root types (#323581) + +2005-12-05 Matthias Clasen <mclasen@redhat.com> + + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-mkdb.in (OutputFunction): Allow parameters to be declared + volatile (this happens in GLib nowadays) + +2005-10-11 Stefan Kost <ensonic@users.sf.net> + + * gtkdoc-mkdb.in: + remove left-over debug-print + +2005-10-10 Stefan Kost <ensonic@users.sf.net> + + * devhelp.xsl: + * gtkdoc-mkdb.in: + enhance gtkdoc devhelp output (#318129) + +2005-10-05 Stefan Kost <ensonic@users.sf.net> + + * gtkdoc-common.pl.in: + revert exchanging   with   + +2005-10-04 Damon Chaplin <damon@gnome.org> + + * gtkdoc-scanobj.in: patch from Andrae Steiner to add missing ';' + (#317938) + +2005-09-29 Stefan Kost <ensonic@users.sf.net> + + * TODO: + additionally point people to the gnome-wiki + + * gtkdoc-mkdb.in: + don't warn on macros with return docs (#314267) + +2005-09-28 Matthias Clasen <mclasen@redhat.com> + + Show signal flags: (#316789) + + * gtkdoc-scangobj.in: Emit flags for signals + as <FLAGS> element in $MODULE.signals + + * gtkdoc-mkdb.in: Emit signal flags similar + to property flags. + + * gtkdoc-mktmpl.in: Handle <FLAGS> here, too. + +2005-09-20 Stefan Kost <ensonic@users.sf.net> + + * doc/README: + * doc/authors.txt: + * doc/gnome.txt: + * doc/sections-file.txt: + * doc/setting-up.txt: + * doc/style-guide.txt: + * gtkdoc-common.pl.in: + adding a note about where the new docs are + +2005-09-15 Damon Chaplin <damon@gnome.org> + + * gtkdoc-scan.in (ScanHeader): + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-mkdb.in (OutputFunction): patch from dodji seketeli to handle + functions returning explicit enums. (#303337) + + Patch from Stepan Kasal: + + * gtkdoc-mkhtml.in, gtkdoc-mkman.in, gtkdocize.in: Add datarootdir + variable, for compatibility with future Autoconf releases. + + * configure.in (PACKAGE_DATA_DIR): Simplify the computation; + use a local macro AC_DEFINE_DIR, based on a macro from Autoconf + macro archive. (#313876) + +2005-09-15 Damon Chaplin <damon@gnome.org> + + * gtkdoc-scangobj.in: Patch from Stepan Kasal to avoid some gcc + warnings. (#312985) + + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: Use brackets around open() arguments to avoid + precedence problems. (#314838) + + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: Output more messages about compilation, linking + and running of scanner, to try to help track down any problems. + Also use "sh -c" to run the scanner (#167688) + + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: patch from Stefan Kost to improve error messages, + though I changed it slightly so it doesn't output errno. + +2005-09-09 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in: + * style.css: + * gtk-doc.xsl: Use a fixed navigation bar at the top of the page. + Patch from Stefan Kost with minor changes by me. (#313569) + +2005-08-18 Damon Chaplin <damon@gnome.org> + + * gtkdoc-scangobj.in: added "const" in a few places to avoid lots + of warnings if all gcc warnings are on. (#312985) + +2005-08-15 Stefan Kost <ensonic@users.sf.net> + + * COPYING-DOCS: + * Makefile.am: + * configure.in: + * omf.make: + * xmldocs.make: + adding the infrastructure for installation of gtkdoc manual + +2005-08-12 Stefan Kost <ensonic@users.sf.net> + + * gtkdoc-mkdb.in: + fix warning about uninitialized var EXPAND_CONTENT_FILES + +Tue Aug 9 12:01:27 2005 tjlocal <timj@imendio.com> + + * autogen.sh: bail out with exit $? for failing programs. + +2005-07-26 Damon Chaplin <damon@gnome.org> + + * gtk-doc.make: Pass DOC_MAIN_SGML_FILE as the main filename to + gtkdoc-mkdb. Avoids creating spurious foo.sgml files in an XML build. + Patch from Malcolm Tredinnick. (#311344) + + Prefix build messages with "gtk-doc: " rather than surrounding them + with "***" which looks like an error. (#170008) + +2005-07-26 Damon Chaplin <damon@gnome.org> + + * README: removed comment about not being able to add section + documentation to source code files, which is not true any more. + +=== release 1.4 === + +2005-07-03 Damon Chaplin <damon@gnome.org> + + * Released 1.4. + +2005-06-20 Matthias Clasen <mclasen@redhat.com> + + * gtkdoc-mkdb.in: Fix typos in warnings. + +2005-06-17 Mikael Hallendal <micke@imendio.com> + + * README: Updated Devhelp web address. + +2005-05-16 Matthias Clasen <mclasen@redhat.com> + + * gtkdoc-mkdb.in: Add "expand-content-files:s" to the GetOptions() call. + +2005-05-10 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb.in: Add an --expand-content-files option + to specify extra files to expand abbreviations in and + copy into the output directory. + + * gtk-doc.make examples/Makefile.am: Add expand_content_files + variable. + + * gtkdoc-mktmpl.in (OutputTemplateFile): Add an + --only-section-tmpl flag so that projects that keep everything + but section descriptions inline can avoid cvs conflicts. + + * gtk-doc.make examples/Makefile.am: Add support for + MKTMPL_OPTIONS + + * configure.in: Up version to 1.4. + +2005-05-02 Matthias Clasen <mclasen@redhat.com> + + * gtkdoc-mkdb.in: Accept C comments between struct name + and struct definition. GObject has an instance of this. + +2005-03-21 Matthias Clasen <mclasen@redhat.com> + + * gtk-doc.dcl: Allow ':' in names. (#169087) + +2005-03-21 James Henstridge <james@jamesh.id.au> + + * gtk-doc.xsl (encoding): output US-ASCII instead of ISO-8859-1. + This ensures that the output will be display correctly when served + as either ISO-8859-1 or UTF-8. + +2005-02-26 Sven Neumann <sven@gimp.org> + + * gtkdoc-mkdb.in (MakeIndexterms): allow space in Since: keywords, + only strip leading and trailing whitespace (bug #168384). + +2005-02-16 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (ScanSourceFile): add support for "@stability:" + in the inline section docs (Brian Cameron). + +2005-02-07 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (MergeSourceDocumentation): allow use of "@...:" in + the source code as well as "@Varargs:". Patch from Benjamin Otte. + #166366. + +2005-02-04 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (ParseStabilityLevel): don't reset $stability if it + isn't Stable/Unstable/Private (Brian Cameron). + (ScanSourceFile): skip whitespace after "SECTION:". + +2005-02-01 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (ScanSourceFile, MergeSourceDocumentation): patch + from Stefan Kost to support section documentation within the source + code (long description, short description, see also and title). + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: patch from Brian Cameron to support stability + levels. + + * gtkdoc-mkdb.in (OutputFunction): + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-common.pl.in (ParseStructDeclaration): patch from Roger Leigh + to add support for the "restrict" keyword. + + * gtkdoc-scan.in (ScanHeader): patch from Roger Leigh to add support + for "unsigned" to one of the regexps. + +2005-01-31 Damon Chaplin <damon@gnome.org> + + * gtk-doc.make (scan-build.stamp): added "2>&1" to grep command to + ignore any errors. + + * gtkdoc-mkdb.in: patch from Stefan Kost to not add '<' '>' around + include files that already have '"' '"' around them, and to try to + gather more information about undocumented symbols. #164462. + +2005-01-28 Damon Chaplin <damon@gnome.org> + + * gtk-doc.make: use dist-hook rather than EXTRA_DIST to copy the + $(DOC_MODULE).types file over, so we can skip this if it doesn't exist. + #156300. + +2005-01-12 Damon Chaplin <damon@gnome.org> + + * README: patch from Stefan Kost to mention GObject classes + and describe the transformation process to XML/SGML and HTML, + and to mention Devhelp. + +=== release 1.3 === + +2005-01-09 Damon Chaplin <damon@gnome.org> + + * Released 1.3. + +2005-01-09 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (MergeSourceDocumentation): output better warnings + using the type information. Patch from Stefan Kost. #161979 + + * gtkdoc-scan.in (ScanHeader): support "typedef struct a *b;". Fixes + last part of #156318. + + * gtkdoc-common.pl.in (ParseStructDeclaration): return an empty array + for forward struct declarations. Part of #156318. + + * gtkdoc-mktmpl.in: + * gtkdoc-mkdb.in: updated a few of the warnings to make them a bit + easier to understand. + +2004-11-22 James Henstridge <james@jamesh.id.au> + + * acconfig.h: remove file, since we don't have a config.h + + * configure.in: make sure $ACLOCAL_FLAGS is passed to aclocal on a + rebuild. + + * autogen.sh: use Automake-1.9 if available, and call aclocal, + autoconf, automake, etc in the same order as autoreconf does. + + * gtkdocize.in: if the AC_CONFIG_MACRO_DIR option is used in the + configure script, copy gtk-doc.m4 to that directory in the source + tree. + +2004-11-16 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (OutputFunction): output "const" rather than + "G_CONST_RETURN". #157674. + + * gtkdoc-mktmpl.in (OutputDeclaration): skip "void" return types but + not if it has modifiers e.g. "void *". #156963. + + * gtkdoc-scan.in (ScanHeader): handle __attribute__. Patch from + Simon Josefsson. #156962. + +2004-10-31 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (OutputStruct): handle opaque/forward struct + declarations. #156318 again. Tiny fix to avoid warnings. + +2004-10-28 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mktmpl.in (ReadDeclarationsFile): + * gtkdoc-mkdb.in (ReadDeclarationsFile): + * gtkdoc-scan.in (ScanHeader): handle opaque/forward struct + declarations. #156318. + +2004-10-25 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (OutputParamDescriptions): use a   after Returns: + so it doesn't break before the colon. + +2004-10-24 Damon Chaplin <damon@gnome.org> + + * gtkdoc-common.pl (ParseEnumDeclaration): handle "typedef enum XXX {" + #156297. Patch from Simon Josefsson. + +2004-10-20 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (ReadDeclarationsFile): set a flag to indicate a + struct has a typedef declaration. + (OutputStruct): better output for structs with typedefs. #83269. + + * gtkdoc-scan.in (ScanHeader): leave the struct declaration as it is. + Don't strip out 'typedef'. Also allow simple "struct foo {". + +2004-10-19 Damon Chaplin <damon@gnome.org> + + * gtkdoc-fixxref.in: use pkg-config to find where GLib is installed + and scan that directory for index files. Also scan $GNOME2_PATH. + These are only used as a last resort. If they are used we have to + output links as absolute URLs, rather than the default relative ones. + +2004-10-18 Damon Chaplin <damon@gnome.org> + + * gtkdoc-common.pl.in (ParseStructDeclaration): support function + pointers that return "foo const *" #141870. + + * gtkdoc-scan.in (ScanHeader): + * gtkdoc-mkdb.in (OutputFunction): + * gtkdoc-mktmpl.in (OutputDeclaration): handle functions with const + or struct return types. #141870 and #148507. + +2004-10-15 Damon Chaplin <damon@gnome.org> + + * gtkdoc-common.pl.in (ParseStructDeclaration) + (ParseEnumDeclaration): moved these here, rather than have 2 copies + in gtkdoc-mkdb.in and gtkdoc-mktmpl.in. + + * gtkdoc-common.pl.in (ParseStructDeclaration): handle struct fields + better. We can now handle things like *foo, ***bar, *baz[12][23], + foo : 25 all on one line. Fixes part of #151219. + Also support the 'short' modifier to fix #90565. + And use $nbsp; rather than spaces to try to avoid splitting + declarations in the output. + Also take an extra arg specifying whether to include parameters in + the function pointer fields. + + * gtkdoc-scan.in (ScanHeader): Deal with array types in typedefs. + (Eg, "typedef unsigned char MD5Digest[16];") From Dan Winship. + Last bit of #151219. + +2004-10-14 Damon Chaplin <damon@gnome.org> + + * gtkdoc-mkdb.in (CreateValidSGMLID): use ":CAPS" rather than + "-CAPS" to distinguish all-caps identifiers, to avoid clashing with + identifiers ending in _caps! Bug #113120. + + * gtkdoc-mkdb.in (MergeSourceDocumentation): if it looks like a + parameter has been described, but not in the right place, output + a better error message. Bug #141871. + + * gtkdoc-mkdb.in (OutputMacro, OutputFunction, GetSignals): allow + the author to use <!--PARAMETERS--> to specify the position of the + parameter table if they want. Hopefully good enough for bug #99567. + (MergeSourceDocumentation): end the paragraph before <!--PARAMETERS--> + and start a new one after it. + + * doc/authors.txt: document <!--PARAMETERS-->. + + * style.css: don't underline links normally, as we output lots of + them and it makes it very cluttered. Only underline links when the + mouse hovers over them, and change the color. Fixes #108037. + + * gtk-doc.make (scan-build.stamp): depend on $(CFILE_GLOB) as well, + since changes in properties need to be picked up by gtkdoc-scangobj. + Bug #52458. + + * gtkdoc-mkdb.in: (ParseStructDeclaration): for fields that are + function pointers, only return the function name, as otherwise the + output gets really messy. Fixes #66618. + + * gtkdoc-mktmpl.in: + * gtkdoc-mkdb.in: + * gtkdoc-scan.in: + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: use '@PACKAGE_DATA_DIR@' instead of + "@PACKAGE_DATA_DIR@" so that it isn't interpolated. It failed when + $prefix was /software/@sys/usr. Fixes #113456. + +2004-10-13 Damon Chaplin <damon@gnome.org> + + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: patch from Olexiy Avramchenko to add 3 new + GdkEvent subtypes. + + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: patch from Benjamin Otte to get rid of + -Wsign-compare warnings. Bug #137013. + +Fri Sep 17 01:13:24 2004 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.xsl: Add the images from the gallery on top + of the refentry they point to. + + * style.css: Move the css bits of the gallery implementation + here. + +Fri Sep 17 00:30:16 2004 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.xsl: Don't generate <link rel="refentry"> + links, since e.g. the GTK+ docs contain MANY refentries. + +2004-09-10 Damon Chaplin <damon@gnome.org> + + * autogen.sh: support automake 1.8. (part of #151219). + + * examples/Makefile.am: require automake 1.6. + + * gtkdoc-scan.in: create an empty MODULE-overrides.txt file if it + doesn't exist. gtkdoc.make expects one to exist. + + * doc/setting-up.txt: updated to document new procedure using + gtkdoc.make. + + * examples/Makefile.am: updated to use gtkdoc.make. + + * examples/configure.in: removed this. gtkdoc.make is used instead + now. + + * examples/README: updated. + + * Makefile.am (EXTRA_DIST): removed examples/configure.in. + +Wed Sep 8 01:12:25 2004 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scan.in (ScanHeader): + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-mkdb.in (OutputFunction): Accept mixtures of * + and const in return types. + +Wed Sep 01 05:58:08 2004 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in: Remove a debug printf + +Tue Aug 24 02:30:08 2004 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.xsl: Add support for a gallery of widget images. + +Wed Jul 28 13:00:54 2004 Jonathan Blandford <jrb@gnome.org> + + * gtk-doc.xsl: remove the examples from the toc. + +2004-07-28 Damon Chaplin <damon@gnome.org> + + * doc/sections-file.txt: mention use of '#' for comments. + + * gtkdoc-mkdb.in: removed HEADER_FILE stuff, since it isn't used now. + +2004-07-23 Damon Chaplin <damon@gnome.org> + + * examples/Makefile.am (all-local): add empty all-local target for + when ENABLE_GTK_DOC is false. (#148209, Martin Quinson) + +Fri Jul 23 13:21:34 2004 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ScanSourceFile): Fix regexps for matching + ignored files. (#148211, Martin Quinson) + +2004-07-03 Matthias Clasen <mclasen@redhat.com> + + * style.css: Add a missing '}' and align arguments to the + top of their descriptions. (#145363, #145364, Mariano + Su�rez-Alvarez) + +2004-05-18 Matthias Clasen <mclasen@redhat.com> + + * gtk-doc.xsl: Let the docbook stylesheets generate + extra <link rel=...> elements. (#140221, Geert Stappers) + +2004-05-10 Geert Stappers <stappers@stappers.nl> + + * TODO: new file, basically a reference to bugzilla. + + * examples/README: tell about gtk-doc.make. + +2004-05-06 Geert Stappers <stappers@stappers.nl> + + * MAINTAINERS: Add myself. + +2004-05-05 Matthias Clasen <mclasen@redhat.com> + + * gtk-doc.xsl: Correct the docbook stylesheet version + in which filtered index support will appear to 1.66. + +2004-04-27 Geert Stappers <stappers@stappers.nl> + + * README: Updated the information on Debian packages. + Removed old author and time stamp line. + +2004-04-21 Matthias Clasen <mclasen@redhat.com> + + * doc/sections-file.txt: Add hint about private types. + + * README: Update. + + * MAINTAINERS: Add myself. + + * gtkdoc-mkdb.in (ReadKnownSymbols): New function which + extracts information about public and private symbols from + the $MODULE-sections.txt file. + (ReadObjectHierarchy): Prune the tree, based on the information + collected by ReadKnownSymbols. + (ReadInterfaces): Also filter out private interfaces here + (ReadPrerequisites): ...and here. + +2004-04-19 Matthias Clasen <mclasen@redhat.com> + + * Makefile.am: Add version-greater-or-equal.xsl. + + * version-greater-or-equal.xsl: New file, implementing + the version-greater-or-equal template for comparing version + numbers. + + * gtk-doc.xsl: Import version-greater-or-equal.xsl and + use the version-greater-or-equal template to a) check that + the xsl stylesheets are not too old and b) to avoid creating + multiple indices if the xsl stylesheets don't support filtered + indices. (#107774) + + * gtkdoc-mkdb.in (MakeIndexterms): Emit role attributes + on indexterms which can be used to create filtered indices + with sufficiently new xsl stylesheets. The required functionality + will appear in version 1.62 of the xsl stylesheets. (#115530) + +2004-04-16 Matthias Clasen <mclasen@redhat.com> + + * style.css: Style information in a separate stylesheet. + + * gtkdoc-mkhtml.in: Copy css files. + + * Makefile.am (gtkdocdata_DATA): Add style.css + + * gtk-doc.xsl: Use a stylesheet instead of hardwiring + styles. (#134683, Vincent Torri) + + * gtkdoc-mkdb.in (GetSignals): Organize the properties + descriptions to fit better with the other sections, and + also display information about allowed and default values. + +2004-04-15 Matthias Clasen <mclasen@redhat.com> + + * gtkdoc-scangobj.in: Use introspection more fully to emit + allowed ranges for integral types and default values. + + * gtkdoc-mkdb.in (GetSignals): Handle missing signal parameter + names better. + +2004-03-04 Damon Chaplin <damon@gnome.org> + + * autogen.sh: fixed URLs to download autoconf/automake/libtool. + Patch from Frederic L. W. Meunier. + +2004-02-16 Damon Chaplin <damon@gnome.org> + + * .cvsignore: added gtk-doc.cat and gtkdocize. + +=== release 1.2 === + +2004-02-16 Damon Chaplin <damon@gnome.org> + + * Released 1.2. + +2004-02-16 Damon Chaplin <damon@gnome.org> + + * gtk-doc.cat.in: removed public ID for gtk-doc.dtd, since we don't + use it any more. + +Sat Feb 14 02:14:27 2004 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.m4: Avoid unnecessary checks if gtk-doc is + disabled. (#134221, Julio M. Merino Vidal) + +Sat Feb 14 02:03:01 2004 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.make: Don't create unneeded empty + directories. (#134319, Julio M. Merino Vidal) + +Sat Feb 14 01:37:38 2004 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.make: Add an empty all-local target to make it work + with non-GNU make. (#134343, Julio M. Merino Vidal) + +Wed Jan 28 00:52:00 2004 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (OutputObjectList): Avoid emitting invalid + docbook markup if there are no objects. Partial fix for #132661. + +Sun Jan 25 22:01:15 2004 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in: Accept both the old and the new XInclude + namespace. (#131675, Edd Dumbill) + +2004-01-23 Thomas Vander Stichele <thomas at apestaart dot org> + + * gtkdoc-mkhtml.in: exit when tools return non-zero so errors can + be caught. + +Thu Jan 15 23:06:10 2004 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.xsl: Set the chunk.fast parameter, to gain some + speed. + +Thu Jan 15 23:05:23 2004 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-fixxref.in: Make it work again without explicit + --module. + +Sat Dec 27 01:36:08 2003 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: + * gtkdoc-mktmpl.in: + * gtkdoc-scan.in: + * gtkdoc-fixxref.in: Add --help. (#126915) + +Sat Dec 27 00:43:42 2003 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ParseEnumDeclaration): + * gtkdoc-mktmpl.in (ParseEnumDeclaration): Support a trailing , + in enum declarations. These are a GNU C extension, but also + blessed by C99. (#129949, Thomas Vander Stichele) + +Sun Nov 16 00:29:03 2003 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: Don't use g_strdown(). (#127028, + David Schleef) + +Sun Nov 16 00:26:05 2003 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: If compiled against GLib >= 2.3.0, look + for properties on interfaces. (#127068, James M. Cape) + +2003-11-03 Dan Winship <danw@ximian.com> + + * gtkdoc-scangobj.in: Clean up $MODULE-scan.o even when using + libtool + + * gtkdoc-scanobj.in: Likewise + + * gtk-doc.make (CLEANFILES): Remove $(MODULE)-scan.o from here + (clean-local): rm -rf .libs + +Wed Oct 8 01:21:54 2003 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scan.in (ScanHeader): Make gtkdoc-scan grok + typedef struct { } foo; in addition to the more baroque + typedef struct _foo foo; struct _foo { }; + (#116807, Malcolm Tredinnick) + +Wed Oct 8 01:21:35 2003 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (OutputParamDescriptions): Remove a pointless + warning. + +2003-10-01 Matthias Clasen <maclas@gmx.de> + + Make signals and properties end up in the right template + file (#116569, Owen Taylor): + + * gtkdoc-mktmpl.in (OutputSignalTemplates): + (OutputArgTemplates): Return a string rather than directly + writing to OUTPUT. + (OutputTemplateFile): Don't interpret $title as the name of + the object to print signal and property templates for. + (UpdateTemplates): Collect signal and property templates for all + objects contained in the section. + +2003-08-10 James Henstridge <james@daa.com.au> + + * acinclude.m4 (JH_PATH_XML_CATALOG): allow caller to specify + actions if found or not found. + (JH_CHECK_XML_CATALOG): when requiring JH_PATH_XML_CATALOG, don't + error out if it is not found. + +2003-08-03 Matthias Clasen <maclas@gmx.de> + + * doc/gnome.txt: Add some hints regarding markup of examples. + +2003-07-22 Matthias Clasen <maclas@gmx.de> + + * configure.in: + * gtk-doc.cat: Fix a problem with the previous commit. + +2003-07-21 Matthias Clasen <maclas@gmx.de> + + Applied patches from Sebastian Rittau to add maintainer mode and an SGML catalog. (#117955, #117956) + + * gtk-doc.cat.in: New catalog file. + * configure.in: Added gtk-doc.catalog to output files. + * Makefile.am: Install gtk-doc.catalog. + + * configure.in: Added AM_MAINTAINER_MODE. + * autogen.sh: Added --enable-maintainer-mode to configure options. + +2003-07-09 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mktmpl.in (ParseStructDeclaration): + * gtkdoc-mkdb.in (ParseStructDeclaration): Accept volatile struct members, which have just + made their appearance in glib. + +2003-06-29 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ExpandAbbreviations): When expanding @param, catch the common @param->field + and @param.field, to reduce the need for littering the C sources with <literal>foo->bar</literal>. + +2003-06-25 Matthias Clasen <maclas@gmx.de> + + Changes for #115528: + + * gtkdoc-mkdb.in (OutputSGML): Collect hierarchy, interfaces, implementations, prerequisites + and derived interfaces separately. + (OutputSGMLFile): Take two more arguments: implementations and derived interfaces. + (GetHierarchy): Also put immediate children in the local tree. + (GetInterfaces): Split into GetInterfaces and GetImplementations. + (GetImplementations): New function to get the implementations of an interface. + (GetDerived): New function to get the known derived interfaces of an interface. + + * gtkdoc-mkdb.in (MakeXRef): Accept a second, optional parameter for the + text of the link. + (ExpandAbbreviations): Add semantic markup inside the links, so that + non-crossreferenced symbols come out properly formatted after link + removal. (#61345) + +2003-06-15 Matthias Clasen <maclas@gmx.de> + + Support for a flat index of all symbols. (#92861) + To use, put an empty <index/> element in your driver document. + + * gtkdoc-mkdb.in (MakeIndexterms): New function, emits an indexterm. + (OutputMacro, OutputTypedef, OutputStruct, OutputEnum, + OutputUnion, OutputVariable, OutputFunction): Use MakeIndexterms. + to emit indexterms for symbols. + + * gtkdoc-mkdb.in (GetSignals): + (GetArgs): Emit Since: information for signals and properties. + +Thu Jun 12 15:55:57 2003 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkhtml.in (declaration): Replace head -1 with -n 1. + (Merge change by Elliot Lee from Red Hat package) + +2003-06-11 Matthias Clasen <maclas@gmx.de> + + * doc/gnome.txt: Updates to the documentation of inline comments. + +2003-06-03 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.spec.in: Add a missing Provides: and include the .pc file. + (#106568, Joe Pranevich) + +2003-05-27 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (GetSignals): + (GetArgs): Add signals and properties to the statistics. + (OutputMissingDocumentation): Emit undocumented signals and + properties. (#113645) + +2003-04-21 Matthias Clasen <maclas@gmx.de> + + * tools/docpercentages.pl: Fix autolinkification for undocumented + symbols. + + * doc/style-guide.txt: Typo fix. + +=== release 1.1 === + +2003-04-18 James Henstridge <james@daa.com.au> + + * Released 1.1. + +2003-04-18 James Henstridge <james@daa.com.au> + + * NEWS: add news items. + + * configure.in: increment version number. + +2003-03-14 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (OutputBook): Fix the public identifier for + DocBook V3.0: Davenport, not DavenPort. + (#108343, Mariano Suarez-Alvarez) + +2003-03-10 James Henstridge <james@daa.com.au> + + * configure.in: associate the chmod commands with the files they + are chmod'ing. This way config.status will always run the correct + chmod command. + +2003-03-04 James Henstridge <james@daa.com.au> + + * configure.in: look up the docbook DTD by public id rather than + system id. + +2003-02-26 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (GetArgs): Prefer template or comment docs over + blurbs only if they're nonempty, otherwise the empty docs from the + templates override all the blurbs. + +2003-02-26 James Henstridge <james@daa.com.au> + + * autogen.sh (THEDIR): set up so that it will choose automake 1.7 + or 1.6 in preference to 1.4. Passes distcheck okay. + + * configure.in: update configure.in script to match + recommendations of newer autoconf's, and add an AC_PREREQ() + statement, since the xml catalog checks are using new autoconf + features. + + * gtk-doc.make (xml-build.stamp): since other bits of the makefile + were assuming xml, may as well hard code --output-format=xml. + +2003-02-19 James Henstridge <james@daa.com.au> + + * Makefile.am: get rid of the dist-hook, and just include the + given files in EXTRA_DIST instead. + + * configure.in: provide meaningful names for the commands. + + * acinclude.m4 (JH_CHECK_XML_CATALOG): add some extra arguments: a + friendly name for the catalog entry, and actions to run if the + entry was found or not. Also include a bit more information in + the config.log file if an error occurs. + +2003-02-18 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkhtml.in (declaration): Avoid the unportable grep + option -q. (#105311) + +2003-02-19 James Henstridge <james@daa.com.au> + + * devhelp.xsl: put chapters that aren't at the top level into the + toc tree (to make gtk's .devhelp tree look better). + + * gtk-doc.spec.in (Requires): make the requires lines match + current requirements ... + + * gtkdoc-mkhtml.in (XSLTPROC): pass --nonet to xsltproc, so we + don't try to download DTDs and XSLT over the net. The configure + checks should catch people who don't have the correct files in + their catalog. + +2003-02-17 James Henstridge <james@daa.com.au> + + * gtkdocize.in (--version): add --version argument. + +2003-02-14 James Henstridge <james@daa.com.au> + + * gtkdoc-mkdb.in (GetOptions): actually accept --tmpl-dir as a + command line option. Based on a patch from Simon Josefsson + <jas@extundo.com>. + + * gtk-doc.xsl: remove the xmlns declaration. Not really needed + for html output anyway ... + +2003-02-13 James Henstridge <james@daa.com.au> + + * devhelp.xsl: remove refsect1's and refsect2's from book tree, as + suggested by Hallski. + + * gtk-doc.make (install-data-local): the change to install images + was superfluous, so I have removed it. + (CLEANFILES): move some more stuff to CLEANFILES from the + distclean-local rule. + +2003-02-12 James Henstridge <james@daa.com.au> + + * gtk-doc.make: add some chmod calls to work around distcheck on + automake >= 1.6. + (install-data-local): copy the images as well as the html files + during install. + (uninstall-local): add an uninstall rule to remove the docs. + (CLEANFILES): add $(DOC_MODULE)-scan.o to the list of files to be + cleaned up. + +2003-02-09 James Henstridge <james@daa.com.au> + + * gtkdocize.in: script used to copy gtk-doc.make into another + module. + + * gtk-doc.make: automake makefile fragment to handle gtk-doc + support in other modules. + + * configure.in: check to make sure DocBook XML DTD and XSLT + stylesheets are present in the XML catalog. + + * acinclude.m4 (JH_CHECK_XML_CATALOG): new macro to check for + entries in the XML catalog. + +2003-02-04 James Henstridge <james@daa.com.au> + + * gtk-doc.m4: a macro to check for gtk-doc. + + * Makefile.am (gtkdocdata_DATA): don't bother installing xml.dcl. + It isn't used anymore (since switching xml mode to xsltproc). + + * gtkdoc-mkhtml.in (gtkdocdir): and here. + + * Makefile.am (gtkdocdatadir): change dir. + + * configure.in: put data files in $(datadir)/gtk-doc/data, so that + they don't all get mixed up with the html docs installed by other + packages. + +=== release 1.0 === + +2003-01-20 Damon Chaplin <damon@gnome.org> + + * Released 1.0. + +2003-01-20 Damon Chaplin <damon@gnome.org> + + * configure.in: bumped version to 1.0, and added SGML_OUTPUT_TYPE + variable, which we set to 'sgml-raw' if we have openjade, or 'sgml' + if we have jade. Added gtk-doc.pc to AC_OUTPUT. + + * gtkdoc-mkhtml.in: used SGML_OUTPUT_TYPE variable to set the output + type of jade/openjade. + + * gtk-doc.pc.in: new pkg-config file, which apps can use to reliably + check the gtk-doc version in future. + + * Makefile.am (pkgconfigdir): install .pc file, and add it to + EXTRA_DIST. + + * examples/configure.in: updated example to use pkg-config for the + version check. + +2003-01-18 James Henstridge <james@daa.com.au> + + * gtkdoc-mkhtml.in (declaration): switch the output type from + "sgml" to "sgml-raw" when using Jade to process docs. This gets + rid of the line breaks inside the tags, which were confusing Lynx. + +2003-01-15 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scan.in (ScanHeader): Remove special cases for Pango and + Bonobo. + * gtkdoc-mkdb.in (OutputDeclaration): + * gtkdoc-mktmpl.in (OutputDeclaration): Remove special cases for + structs named BlablaClass. (#95398) + + * gtkdoc-mkdb.in (GetInterfaces): Fix an off-by-one error. + (#103466, Josh Parsons) + +2002-12-28 Chema Celorio <chema@celorio.com> + + * gtkdoc-scan[g]obj.in: add "void" to functions with no parameters, + avoids warning with -Wmissing-prototypes when compiling + {module}-scan.c + +2002-12-16 James Henstridge <james@daa.com.au> + + * gtk-doc.spec.in: require perl >= 5.6.0 + + * configure.in: require Perl >= 5.6.0 + + * gtkdoc-fixxref.in: add "use bytes;" to fix malformed UTF-8 + character errors when run with a UTF-8 locale. + +2002-12-16 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (OutputSGMLFile): Don't emit the additional + anchors in the title which breaks the generated html (the title + text is copied around). Instead, put the anchors before the + synopsis. This isn't perfect, but the best we can achieve without + stylesheet hackery. + +2002-12-13 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in: Add an --ignore-files option which can be used + to omit files or directories from scanning. + (OutputSGMLFile): Emit anchors for all objects contained in the + file to avoid dangling links. + (OutputMissingDocumentation): Emit deprecated symbols after + undeprecated ones. + +2002-12-12 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scan.in (ScanHeader): Also recognize "positive" guards + like #ifdef GTK_ENABLE_BROKEN. + +2002-12-11 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.xsl: Change XPath path to "//anchor|//refentry" for the + generation of index.sgml. The previous path "//anchor|refentry" + was not matching any refentrys. + +2002-12-09 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mktmpl.in (UpdateTemplates): Emit unused class structs + to $MODULE-unused.txt. + +2002-12-08 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (OutputStruct): Don't emit private parts + of class structs to parameter lists in docs. Remove leftover + debugging output. + + * gtkdoc-mktmpl.in (OutputDeclaration): Don't emit private parts + of class structs to parameter lists in templates. + +2002-12-06 Matthias Clasen <maclas@gmx.de> + + Improved /*< private >*/ handling: (#95398) + + * gtkdoc-mkdb.in (OutputStruct): Handle /*< public >*/ and + /*< private >*/ for all structs. Default to private for object and + class structs, to public for all other structs. + + * gtkdoc-scan.in (ScanHeader): Emit declarations for class structs + to $MODULE-decl.txt. + +2002-12-05 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-mkdb.in (ReadTemplateFile): Support @Since: and + @Deprecated: as a way to specify since and deprecated information + in template files. This works for all kinds of symbols, even those + which normally don't have parameter lists. + +2002-12-02 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (MakeDeprecationNote): Support multi-paragraph + deprecation notes. + +2002-11-29 James Henstridge <james@daa.com.au> + + * gtkdoc-mkhtml.in: copy the navigation images for both XML and + SGML cases. + + * gtk-doc.dsl.in: update DSSSL stylesheets to match layout of XSL + ones. + +2002-11-29 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scan.in (ScanHeader): Make deprecation guards work with + both + #ifndef DEPRECATION_GUARD + #if !defined(DEPRECATION_GUARD) || defined(FOO_COMPILATION) + The second form is used in GDK and GTK+ to include selected + deprecated symbols when compiling the library itself. + +2002-11-27 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in: Parse to new tags in inline doc comments, + Since: and Deprecated:, which can be placed after the Returns: + tag. Emit the Since: information (which is expected to be just a + version number) after the parameters and the Deprecated: + information (which is expected to be one or more full sentences) + inside the deprecation warning. + Warn if a Deprecated: tag is found on a symbol which is not + guarded by a deprecation guard in the header. + +2002-11-26 James Henstridge <james@daa.com.au> + + * gtkdoc-mkhtml.in: set gtkdoc-bookname and gtkdoc-version + parameters in sgml mode, and don't bother with the sed run after + processing with jade. + In XML mode, pass the version number in as a parameter too. + + * gtk-doc.dsl.in ($user-html-header$): add <meta> tag if + gtkdoc-version is set. + (generate-index-mode): if gtkdoc-bookname is set, add it to the + hrefs in the index file, like the XSLT sheets do. + + * gtk-doc.xsl: add gtkdoc.version parameter, and use it to add a + <meta> tag with the gtk-doc version number. + +=== release 0.10 === + +2002-11-16 Damon Chaplin <damon@gnome.org> + + * Released 0.10. + +2002-11-16 Damon Chaplin <damon@gnome.org> + + * configure.in: bumped version to 0.10. + + * Makefile.am (EXTRA_DIST): added MAINTAINERS. + + * README: updated requirements info, mainly to add XML stuff. + + * NEWS: added news for 0.10 + + * MAINTAINERS: + * AUTHORS: updated my email address. + +2002-11-16 James Henstridge <james@daa.com.au> + + * gtk-doc.xsl: output HTML in ISO-8859-1 (latin1), as using UTF-8 + can trigger misinterpretation of web pages when the web server + asserts that the document is encoded in latin1 in the mime type. + +2002-11-15 James Henstridge <james@daa.com.au> + + * gtk-doc.xsl: small changes to make the output closer to valid + HTML. + + * gtkdoc-fixxref.in (MakeXRef): when substituting in cross + references, use lower case element and attribute names, and quote + the attribute value. + +2002-11-12 James Henstridge <james@daa.com.au> + + * gtkdoc-mkdb.in: put content of parameter descriptions in + <simpara> elements instead of <para>'s. This makes the generated + HTML more compact, as it will omit the <p> tag inside the list + item. + + * gtk-doc.xsl: adjust stylesheet a little. + +2002-11-10 James Henstridge <james@daa.com.au> + + * gtk-doc.xsl: change style for documentation. + + * gtkdoc-mkhtml.in (declaration): copy PNG files to the html + directory. + +2002-11-10 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (GetArgs): Expand abbreviations in source doc + comments. + +2002-11-09 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mktmpl.in (OutputSignalTemplates): Don't replace template + param names with meaningless argn names generated by gtkdoc-scangobj. + + * gtkdoc-mkdb.in (GetSignals): Use argument names from source doc + comments, if available. + (GetArgs): Use source doc comments instead of blurb, if available. + (ScanSourceFile): Also accept object::signal and object:property + symbols. + (MergeSourceDocumentation): For signals only, prefer source doc + param names over template param names. + +Fri Nov 8 15:10:57 2002 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb.in (GetPrerequisites): Add missing <para> + here too. + +Mon Nov 4 17:17:40 2002 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb.in (MergeSourceDocumentation): Warn + when overriding docs in template file by inline comments. + + * gtkdoc-mkdb.in (GetInterfaces): Add missing <para> in + "Implemented interfaces" output. + +2002-10-29 Damon Chaplin <damon@ximian.com> + + * gtkdoc-scangobj.in: in get_type_name() set is_pointer to TRUE for + subtypes of G_TYPE_BOXED and G_TYPE_POINTER. This means we get things + like "GtkTreeIter *iter" rather than "GtkTreeIter iter" which was + incorrect. Also return 'GParamSpec*' for G_TYPE_PARAM. + in lookup_signal_arg_names() changed GtkNotebook::switch-page + page argument to guint. And fixed a few other entries. + Also fixed argument numbering, so we don't get 2 "widget" arguments. + + * gtkdoc-scanobj.in: add ';' after unlink command to avoid warning. + +2002-10-20 Matthias Clasen <maclas@gmx.de> + + * examples/Makefile.am (SCANOBJ_FILES): Add $(DOC_MODULE).prerequisites. + + * gtkdoc-mkdb.in: Read $MODULE.prerequisites and put list of + prerequisites below the object hierarchy for interfaces. + + * gtkdoc-scangobj.in: Write information about interface + prerequisites to $MODULE.prerequisites. + +2002-10-15 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: Sort paramspec arrays for + greater stability and less random tmpl file diffs. + +2002-10-14 Matthias Clasen <maclas@gmx.de> + + * examples/Makefile.am (SCANOBJ_FILES): Add $(DOC_MODULE).interfaces. + + * gtkdoc-mkdb.in: Read $MODULE.interfaces and put lists of + implemented interfaces/known implementations below the object + hierarchy for classes/interfaces. + + * gtkdoc-scangobj.in: Write interface information to + $MODULE.interfaces. + +2002-10-12 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: Make interface appear in the object hierarchy. + +2002-10-11 Matthias Clasen <maclas@gmx.de> + + * gtk-doc.xsl: use 'UTF-8', not UTF-8 for default.encoding, to + make the encoding actually appear in the resulting HTML. + +2002-10-09 James Henstridge <james@daa.com.au> + + * gtkdoc-mkdb.in: set $doctype_header to "" for the SGML case, as + we don't add a doctype to the beginning of SGML fragments. + +Tue Sep 17 01:07:51 2002 Jonathan Blandford <jrb@gnome.org> + + * gtk-doc.xsl: output the chunks in UTF-8 so other tools can use + them. + +2002-09-03 James Henstridge <james@daa.com.au> + + * gtk-doc.xsl: turn on rendering of variablelists as tables, and + set CSS rules to style .variablelist instead of .informaltable. + + * gtk-doc.dsl.in (variablelist): override the variablelist handler + instead of the tgroups. + + * gtkdoc-mkdb.in (OutputStruct): use a <variablelist> for listing + the field descriptions. + (OutputEnum): same here. + (OutputParamDescriptions): and here. + +2002-08-12 James Henstridge <james@daa.com.au> + + * gtk-doc.xsl: include devhelp.xsl, and call generate.devhelp when + processing the docbook/xml input. + + * devhelp.xsl: new file, implements .devhelp file output. + +2002-08-18 Havoc Pennington <hp@pobox.com> + + * autogen.sh: hardcode aclocal-1.4/automake-1.4 so that users with + both automake 1.6 and 1.4 installed get the right automake. Means + compilation from CVS will now require the latest automake 1.4 + release, or manually creating symlinks called "automake-1.4" and + "aclocal-1.4" + +2002-08-08 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: Make sure blurbs end with a '.' + +2002-08-08 James Henstridge <james@daa.com.au> + + * gtk-doc.xsl: add a gtkdoc.bookname param, and include it in the + index.sgml output (if not empty). + + * gtkdoc-mkhtml.in: only perform the sed operation if we are using + Jade, and pass the module name as a parameter when using xsltproc. + +2002-08-04 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: Don't try to list signals on types which + don't support signals, e.g. boxed types. + +2002-06-14 jacob berkman <jacob@ximian.com> + + * gtkdoc-mkdb.in: do the version check before help, so --version + doesn't output --help (should fix recent build bustage) + +2002-06-12 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in: Make header-grabbing work without an explicit + --main-sgml-file argument. + + * gtkdoc-mkdb.in: Emit the object hierarchy as a <screen> rather + than a <literallayout>, since the Docbook XSL stylesheets don't + handle <link>s inside <literallayout>. + + * gtkdoc-mkdb.in: Decide whether to generate standalone documents + for XIncluding or entities based on the presence of the XInclude + namespace declaration on the document element. + +2002-06-09 James Henstridge <james@daa.com.au> + + * gtkdoc-mkdb.in: try to grab the header off the top of the main + sgml file. + +2002-05-31 James Henstridge <james@daa.com.au> + + * gtkdoc-mkdb.in (OutputSGML): put XIncludes in the $book_bottom + variable. + (OutputBook): add the XInclude namespace declaration to the book + element. + + * gtkdoc-mkhtml.in (declaration): if the document looks like XML, + process it with xsltproc. + + * configure.in: check for xsltproc. + + * gtk-doc.xsl: start of XSLT template for converting docbook/xml + to HTML. + +2002-06-03 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ConvertSGMLChars): Don't use Posix character + classes. Perl < 5.6 doesn't have them; and the API doc autobuilder + on widget.gnome.org has an old Perl. + +2002-05-29 Matthias Clasen <maclas@gmx.de> + + Fixes for #77193: + + * gtkdoc-mkdb.in (OutputSGML): Call GetSignals, GetArgs and + GetHierarchy for each symbol here and accumulate. + (OutputSGMLFile): Get signal, argument and hierarchy information + from the caller. + (GetSignals, GetArgs, GetHierarchy): Don't wrap the return value + in a refsect1, so that the results of multiple calls can be accumulated. + +2002-05-28 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ConvertSGMLChars): Make this work correctly + for empty elements and XML comments in doc comments. + +2002-05-27 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ReadTemplateFile, OutputSGMLFile): + Use only the basename of the template file in the key for the + symbol table, in order to decouple the file extensions of the + template files and the generated entities (we want to generate + .xml entities from .sgml template files when emitting XML). + +2002-05-25 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ConvertSGMLChars): New function which tries to + be a bit more clever when escaping SGML syntax characters. + (ScanSourceFile): Use ConvertSGMLChars instead of CreateValidSGML. + This reduces the work needed to make gtk-doc emit XML (where <, & + and friends must always be escaped). + +2002-05-18 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkhtml.in: Detect whether we're processing SGML or XML. + + * gtkdoc-mkdb.in: New option --output-format to switch between + SGML and XML output. + + * Makefile.am (EXTRA_DIST): Add xml.dcl + + * xml.dcl: The XML declaration. + +2002-05-06 jacob berkman <jacob@ximian.com> + + * gtkdoc-scangobj.in: add an include for the GTK_CHECK_VERSION + macro + +2002-05-05 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: Output style properties. (#80659) + + * gtkdoc-mkdb.in (GetArgs): Return separate sections for + properties, child properties and style properties. (#80659) + +2002-05-03 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in: Fix for segfault in scangobj-generated C + program on Solaris. (#80606, Jacob Berkman) + +2002-05-01 Matthias Clasen <maclas@gmx.de> + + * tools/docpercentages.pl: Add the script which Owen uses for the + d.g.o online API docs. Its easier to keep in sync here. + + * gtkdoc-mkdb.in (OutputMissingDocumentation): Fix + $MODULE-undocumented.txt for d.g.o online API docs. + + * gtkdoc-mkdb.in (GetArgs): Use blurbs for property documentation. + + * gtkdoc-scangobj.in: Output child properties. Output nicks and + blurbs for properties. + +2002-04-28 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-mkdb.in (ScanSourceFile): Don't scan for return value + descriptions unnecessarily. (#65997) + +2002-03-11 Matthias Clasen <maclas@gmx.de> + + * gtkdoc-scangobj.in, gtkdoc-mkdb.in: Create docs for signals on interfaces. + +2002-02-01 Damon Chaplin <damon@ximian.com> + + * configure.in: check for openjade or jade. Patch from Stefan Kost + <kost@imn.htwk-leipzig.de>. + + * gtkdoc-mkhtml.in: use @JADE@ so the correct version of jade is used. + + * autogen.sh: commented out autoheader since we don't have a config.h. + +=== release 0.9 === + +2002-01-18 Damon Chaplin <damon@ximian.com> + + * Released 0.9. + +2002-02-01 Damon Chaplin <damon@ximian.com> + + * examples/Makefile.am: added SCANOBJ_OPTIONS in case the module needs + to pass options to gtkdoc-scanobj or gtkdoc-scangobj. + +2002-01-24 Damon Chaplin <damon@ximian.com> + + * tools/gtk-doc.el: added Zucchi's emacs lisp for automatically adding + skeleton comment blocks above functions. Very handy! + +2002-01-23 Damon Chaplin <damon@ximian.com> + + * configure.in: bumped the version to 0.9, so GTK+ can depend on this + if it wants to. + + * gtkdoc-scangobj.in: we now default to calling g_type_init() to + initialize the type system, rather than gtk_init(). This means you + don't need an X connection to build the docs any more. Hurrah! + Also added a '--type-init-func' argument so you can change the + function to be called. GTK+ uses --type-init-func="gtk_type_init(0)". + + * gtkdoc-scan.in (ScanHeader): removed 'Found object' debug message. + +=== release 0.8 === + +2002-01-18 Damon Chaplin <damon@ximian.com> + + * Released 0.8. + +2002-01-18 Damon Chaplin <damon@ximian.com> + + * Makefile.am (EXTRA_DIST): added gtk-doc.dcl to EXTRA_DIST. + +2002-01-18 Damon Chaplin <damon@ximian.com> + + * gtkdoc-scangobj.in: Reverted jacob's patch for this release, since + it breaks GTK+ and possibly other packages. I'll re-apply it after + the release, so we can fix everything in CVS. + +2002-01-18 jacob berkman <jacob@ximian.com> + + * gtkdoc-scangobj.in: default to calling g_type_init(), remove + --nogtkinit argument and replace with a more flexible + --type-init-func + +2002-01-18 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in (ScanSourceFile): patch from Matthias Clasen + <matthiasc@poet.de> to only strip first space after '*' in source + code comment blocks, so example code can be indented as desired. + Bug #68216. + +Wed Nov 21 16:50:35 2001 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb,tmpl.in: Add some extra quoting to + error messages to make it clearer what is going on + with trailing commas on enumeration declarations. + +Wed Nov 21 16:00:45 2001 Owen Taylor <otaylor@redhat.com> + + * Applied patch from Matthias Clasen to use a modified + .dcl file with the 44 character name length limit removed. + (#61342) + +2001-10-17 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in: applied patch from Matthias Clasen + <matthiasc@poet.de> to take a --sgml-mode argument which means + all comment blocks in the source code are assumed to be DocBook + (i.e. we don't convert '<', '>' and '&' to '<' etc. + +2001-10-09 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in (OutputMissingDocumentation): changed %.2f to %.0f + so hopefully the automated reports on developer.gnome.org will work + OK again. + +2001-10-02 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-mkdb.in (OutputFunction): applied patch from + matthiasc@poet.de (Matthias Clasen) to handle G_CONST_RETURN in a + parameter list. Bug #61341. + +2001-10-02 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in (OutputMissingDocumentation): applied patch from + matthiasc@poet.de (Matthias Clasen) to output percentages better. + Bug #61467. + Also set percent to 100 if total is 0, avoiding divide-by-zero. + +2001-10-02 Damon Chaplin <damon@ximian.com> + + * examples/Makefile.am (DOC_OVERRIDES): define as an empty string, + even when not used. + +2001-09-13 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in (OutputMissingDocumentation): initialize buffer to "". + Fix for SGI from David Kaelbling <drk@sgi.com>. + +Sat Sep 8 14:08:51 2001 Jonathan Blandford <jrb@webwynk.net> + + * gtkdoc-scan.in (ScanHeader): recognize GET_IFACE macros + +2001-09-08 Havoc Pennington <hp@pobox.com> + + * gtkdoc-mkdb.in (GetArgs): Title the section on object properties + "Properties" instead of "Args" + +2001-08-14 Laszlo Peter <laca@ireland.sun.com> + + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: change \n's to \\n's in perl scripts + generating C code. + +2001-08-12 Jens Finke <jens@gnome.org> + + * Updated gtk-doc.spec.in file to match gpp standard. + +=== release 0.7 === + +2001-08-04 Damon Chaplin <damon@ximian.com> + + * Released 0.7 + +2001-08-04 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in (OutputFunction): + * gtkdoc-mktmpl.in (OutputDeclaration): patch from Lowell Johnson + <ldjohn@usgs.gov> to accept things like "long long", "short int", + "char test[][CLEN]" as function parameters. + +2001-07-20 Anders Carlsson <andersca@gnome.org> + + * gtkdoc-scangobj.in: Remove argument to g_type_init (); + +2001-07-09 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in (ParseStructDeclaration): accept G_CONST_RETURN + modifier for function return values. gtkdoc-mktmpl.in already had this. + +Thu Jun 21 11:57:16 2001 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-scangobj.in: Conform to changes in GObject API + for property retrieval. + +2001-05-25 Peter Williams <peterw@ximian.com> + + * gtkdoc-mkdb.in (ScanSourceFile): Skip single-line comments -- + prevents barfing on ORBit-generated files. + +2001-05-20 Damon Chaplin <damon@ximian.com> + + * examples/Makefile.am (sgml-build.stamp): replaced use of wildcard + (which isn't portable) with original *.sgml. I think this just means + that the first time you try to build the docs it will fail, but if + you run make again it will work. + + * doc/setting-up.txt: explained that make may fail the first time. + +2001-05-19 Damon Chaplin <damon@ximian.com> + + * README: + * doc/README: + * doc/setting-up.txt: + * doc/sections-file.txt: + * doc/authors.txt: updated docs to cover simpler setup procedure. + + * doc/gtk_button.txt: + * doc/manpage: + * doc/manpage.man: + * doc/notes.txt: removed out-of date stuff. + + * Makefile.am (dist-hook): updated so it doesn't try to remove old + examples subdirectory stuff. + +2001-05-19 Damon Chaplin <damon@ximian.com> + + * examples/gnome/*: + * examples/gnomeui/*: removed out-of-date example files. + + * examples/configure.in: + * examples/Makefile.am: new example setup mostly copied from GTK+. + + * examples/README: describe the example configure.in/Makefile.am. + +2001-05-19 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in: added --help option and changed output slightly to + make more compatible with XML. Patch from Toshio Kuratomi + <badger@prtr-13.ucsc.edu> + +2001-05-19 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mktmpl.in (OutputDeclaration): + * gtkdoc-mkdb.in (OutputFunction): changed a '?' to a '*' so we accept + multi-dimensional array function parameters. Patch from Paolo Casarini + <casarini@CS.UniBO.IT> + +2001-05-12 Damon Chaplin <damon@ximian.com> + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: used "*pos = 0" to avoid problems with backslashes + in '\0'. + + * configure.in: removed dsssl dirs stuff, since we use public entities + now. + + * gtkdoc-mkdb.in (OutputBook): if there is no main SGML file we create + it here. Also added a --main-sgml-file option so we know where to put + it. + + * gtkdoc-scan.in: if there is no MODULE-sections.txt file, we copy + the MODULE-decl-list.txt file to it. The user can tweak it later. + +2001-05-11 Damon Chaplin <damon@ximian.com> + + * gtk-doc.spec.in: applied patch from Toshio Kuratomi + <badger@prtr-13.ucsc.edu>. + +2001-05-07 Joakim Ziegler <joakim@ximian.com> + + * gtkdoc-mkdb.in: Added option --outputallsymbols to create a symbol list + in the module doc dir. + + * gtkdoc-mkdb.in: Added functionality to output a list of undocumented + symbols in a module, most of is is in OutputMissingDocumentation. + + * gtkdoc-scan.in: Small scanning fixes to facilitate the doc coverage + output mentioned above. + +2001-04-25 Federico Mena Quintero <federico@ximian.com> + + * gtkdoc-scanobj.in: Added missing output-dir in the call to + GetOptions(). + +2001-04-24 Damon Chaplin <damon@ximian.com> + + * gtkdoc-scanobj.in: copied --outputdir option from gtkdoc-scangobj.in. + +Fri Apr 13 15:25:44 2001 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb.in: Restore call to OutputBook that was accidentally + deleted. + +Thu Apr 12 17:57:12 2001 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-scangobj.in: Add a --outputdir option (sort of hacky. + Need this because $CC, $LD can include relative paths if they + are based on $LIBTOOL) + +2001-03-26 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mkdb.in (ReadSourceDocumentation): scan .h files as well, + so macros can be documented there if desired. Patch from + Yoann Vandoorselaere <yoann@mandrakesoft.com> + + * gtkdoc-mkhtml.in (gtkdocdir): use 'test -f' rather than 'test -e' + which is GNU-specific. + +Thu Mar 8 17:26:29 2001 Tim Janik <timj@gtk.org> + + * gtkdoc-scangobj.in: fix signal param type handling. + +Tue Mar 6 23:21:46 2001 Jonathan Blandford <jrb@redhat.com> + + * gtkdoc-scanobj.in: Add gobject support. Now works on files that + don't link against GTK. + +Sat Mar 3 17:43:42 2001 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-{scan,mktmpl,mkdb}.in: Add support for G_CONST_RETURN. + (Right now, it will appear as G_CONST_RETURN in the output - + I'm not sure that's right - perhaps it should be converted + to const.) + +2001-02-20 Michael Meeks <michael@ximian.com> + + * gtkdoc-mktmpl.in: s/TRUE/1/ + +2001-02-19 Damon Chaplin <damon@ximian.com> + + * gtkdoc-mktmpl.in (UpdateTemplates): fixed bug handling the $changed + flag. + +2001-02-17 Damon Chaplin <damon@ximian.com> + + * gtkdoc-scan.in (ScanHeaders): + (ScanHeader): patch from Johannes Stezenbach <js@convergence.de> + so we don't use '\b' in the regexp to match files/dirs to ignore. + '\b' can match '_' so we matched things we shouldn't have. + +Mon Feb 12 12:50:57 2001 Owen Taylor <otaylor@redhat.com> + + * configure.in: Up version. + +Sun Feb 11 18:35:07 2001 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mktmpl.in: Add a timestamp file for the + templates like sgml.stamp + + * gtkdoc-mktmpl.in (OutputUnusedTemplates): Write the + symbols out in sorted order instead of hash table + order to reduce conflicts. + +Mon Feb 5 16:48:51 2001 Owen Taylor <otaylor@redhat.com> + + * configure.in gtk-doc.dsl.in: Remove checks for DSSSL - use a + public entity instead. + + * gtkdoc-scangobj.in: Fix to work with libtool better. + +2001-01-30 Havoc Pennington <hp@pobox.com> + + * gtkdoc-fixxref.in, gtkdoc-mkdb.in, gtkdoc-mktmpl.in, + gtkdoc-scan.in, gtkdoc-scangobj.in, gtkdoc-scanobj.in: + Added -*- cperl -*- magic, and --deprecated-guards + option. + +2001-01-23 Damon Chaplin <damon@helixcode.com> + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + * gtkdoc-scan.in: + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: changed so that they only update files when + necessary (they write new versions of the files out, then use 'cmp' + to compare with the existing versions to see if they have changed.) + This should make it easier to do proper dependency rules in Makefiles, + and it may cut down on CVS traffic. + + * gtkdoc-mkhtml.in: update a timestamp file (html.stamp) after running. + * gtkdoc-mkdb.in: update a timestamp file (sgml.stamp) if any of the + DocBook SGML files have been changed. So hopefully you can now use + rules like this to avoid unnecessary regeneration of the HTML: + + all-local: + $(MAKE) scan + $(MAKE) templates + $(MAKE) sgml + $(MAKE) html.stamp + + html.stamp: sgml.stamp $(EXTRA_SGML_FILES) + $(MAKE) html + + (I've tried this with the old GTK+ reference API docs and it seems to + work well.) + + * gtkdoc-scangobj.in: + * gtkdoc-scanobj.in: + * gtkdoc-scan.in: + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: + * gtkdoc-mkhtml.in: + * gtkdoc-mkman.in: + * gtkdoc-fixxref.in: + Added '--version' command-line arg to all shell & perl scripts, so + you can check for version 0.5 if you want to use the above rules. + (If 0.4 is used make will probably complain about not knowing how to + to build sgml.stamp.) + + * gtkdoc-common.pl.in: new file to contain shared routines. + For now it just contains the UpdateFileIfChanged routine for the above. + We can move the duplicated routines here in future, though the use of + global variables makes this a bit awkward. + + * configure.in (PACKAGE_DATA_DIR): calculates the data dir and + substitutes it so that the scripts know where gtkdoc-common.pl + is installed. Also added gtkdoc-common.pl to AC_OUTPUT. + + * Makefile.am: added gtkdoc-common.pl to gtkdocdata_DATA. + + * gtkdoc-mkhtml.in: deleted the old index.sgml file, since it causes + problems if it is owned by root (e.g. after you run 'make install' as + root. jade prompts you about overwriting it, which is annoying. + +2001-01-10 Havoc Pennington <hp@redhat.com> + + * gtkdoc-mktmpl.in: Only move old file to backup if the old file + exists, and have better error messages when doing the backups + +Mon Jan 8 14:57:29 2001 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mktmpl.in: Canonicalize signal and argument + names to -, not _. + + * gtkdoc-scangobj.in: Fix up for GParamSpec. + +2001-01-04 Fr�d�ric Gobry <frederic.gobry@smartdata.ch> + + * gtkdoc-scan.in: fixed matching of < private_header > directive + +2000-12-19 Damon Chaplin <damon@helixcode.com> + + * gtkdoc-scanobj.in: + * gtkdoc-scangobj.in: added default cases to get_type_name(). + +2000-12-10 Arturo Tena <arturo@directmail.org> + + * gtkdoc-scanobj.in (get_type_name): + * gtkdoc-scangobj.in (get_type_name): fixed syntax error: forgotten + to close a switch statement. + +2000-12-10 Damon Chaplin <damon@helixcode.com> + + * gtk-doc.spec.in: added spec.in file from John Gotts + <jgotts@linuxsavvy.com>. + + * configure.in (AC_OUTPUT): added spec file. + + * Makefile.am: uncommented spec file stuff, now that we have one. + + * gtkdoc-scanobj.in (get_type_name): + * gtkdoc-scangobj.in (get_type_name): updated to use the type numbers + rather than the type names, which were changed in GTK+ 1.2. This + should fix a problem where GTK_TYPE_STRING arguments were output as + 'GtkString *arg' instead of 'gchar *arg'. + + I'm still not sure what to output for the structured types such as + GTK_TYPE_SIGNAL/ARGS/FOREIGN/CALLBACK/C_CALLBACK. Should these be + expanded to several arguments to the signal handler? + +2000-11-25 Dan Mueth <d-mueth@uchicago.edu> + + * help/manual/C/: created this path + * gtk-doc-manual.sgml: Put part of the outline into SGML. + Chris plans to put rest of outline in here and start + writing. + * fdl-appendix.sgml: The FDL in SGML. We will probably post + these on the web as a single document (book) so we will + need the FDL to be included as an appendix. + +Fri Nov 3 07:21:34 2000 Tim Janik <timj@gtk.org> + + * gtkdoc-mkdb.in: + (ParseStructDeclaration): + (OutputStruct): + * gtkdoc-mktmpl.in: + (ParseStructDeclaration): + support /*<protected>*/ equivalently to /*<private>*/ + +Fri Nov 3 07:15:58 2000 Tim Janik <timj@gtk.org> + + * gtkdoc-mktmpl.in: + * gtkdoc-mkdb.in: + (ReadTemplateFile): only eat up the first space (if at all + present) after "@param:" to preserve indentation for multiline + parameter descriptions. + +2000-10-30 Raja R Harinath <harinath@cs.umn.edu> + + * gtkdoc-mkdb.in (ParseStructDeclaration): + Stop scanning at '}' only when it starts a line. + * gtkdoc-mktmpl.in (ParseStructDeclaration): Likewise. + +Mon Oct 30 02:59:54 2000 Tim Janik <timj@gtk.org> + + * gtkdoc-scangobj.in: use g_signal_list_ids(). + +Sun Oct 29 02:54:51 2000 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-scangobj.in: Sort signal types arrays for + greater stability and less random tmpl file diffs. + +Sun Oct 29 01:02:35 2000 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-scangobj.in: Work properly with GSignal + +=== release 0.4 === + +2000-10-21 Damon Chaplin <damon@helixcode.com> + + * Released 0.4 + +2000-10-14 Damon Chaplin <damon@helixcode.com> + + * AUTHORS: + * MAINTAINERS: changed my email address. + + * Makefile.am (dist-hook): remove the CVS dirs from the dist. + + * doc/setting-up.txt: typo. + +Fri Oct 6 17:51:50 2000 <otaylor@redhat.com> + + * gtkdoc-scan.in gtkdoc-mkdb.in: Allow multiple + --source-dir options. + +Thu Sep 7 11:41:12 2000 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb.in: Ignore all . files when scanning directories. + + * gtkdoc-scan.in: Add support for GLIB_VAR, GDKVAR, + etc when looking for variable declarations. + + * gtkdoc-scan.in: Recognize GET_CLASS macros. + + * gtkdoc-scangobj.in: Support .lo intermediate files + with libtool. + +Wed Sep 6 17:57:33 2000 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-scangobj.in: Add gtkdoc-scangobj scanner for + GObject type system. + + * gtkdoc-scanobj.in: Allow setting $LD to allow separating + compilation and linking and thus to allow using libtool. + + * gtkdoc-fixxref.in (ScanIndices): Allow HTMLDIR + not to be present yet. + +Tue Sep 5 23:37:53 2000 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-fixxref.in: Add a --extra-dir option to + allow scanning of additional uninstalled HTML + directories. + + * gtkdoc-scan.in (ScanHeaders): Honor subdirectories + appearing in --ignore-headers. + + * gtkdoc-mkdb.in: Append -CAPS to all all-caps identifiers + to prevent an infinite expansion of special cases. + + * gtkdoc-fixxref.in: Add a --module-dir option to + allow fixing references in an uninstalled tree. + + * gtkdoc-mkdb.in gtkdoc-mkhtml.in: Simple handling + for macros with embedded commas in enumeration + declarations. + +Mon Aug 28 18:18:53 2000 Owen Taylor <otaylor@redhat.com> + + * configure.in (DSSSL_DIR): Remove check for AM_PATH_GTK + since the dependency is only run-time not install-time, + and to avoid dependency loops. + +2000-06-21 Damon Chaplin <damon@helixcode.com> + + * gtkdoc-mkdb.in: fixed <INCLUDES> bug, I think. + +Wed Feb 9 11:29:25 2000 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-scan.in: Hack to avoid misidentifying structures + as GtkObjects within Pango. + +1999-12-15 Raja R Harinath <harinath@cs.umn.edu> + + * gtk-doc.dsl.in ($generate-chapter-toc$): Add missing close + parenthesis. + +1999-11-23 Raja R Harinath <harinath@cs.umn.edu> + + * gtk-doc.dsl.in: Use the (define (foo) ...) syntax rather than + the uglier (define foo (lambda () ...)) syntax. + ($generate-chapter-toc$): Simplify. + ($shade-verbatim-attr$): Simplify. Use ($table-width$) instead of + "100%" for width (See docs. of NWalsh Docbook DSSSL Stylesheets + for an explanation). + +1999-09-20 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtk-doc.dsl.in: If a Chapter has role="no-toc" we don't generate a + table of contents. This is useful if a better contents page has been + added manually, e.g. for the GTK+ Widgets & Objects page. (But it is + a bit of a hack.) + + * gtkdoc-scanobj.in: added --nogtkinit flag which will make it call + gtk_type_init() rather than gtk_init(). This is useful when it is + run automatically to update the docs by a cron job or similar and a + connection to an X server is not desirable. However, if any widgets + need a connection to X in their class init function then this can't + be used (e.g. GtkFontSelection at present). + +Mon Sep 20 09:09:12 1999 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb.in gtkdoc-mktmpl.in: (ParseStructDeclaration): + Fixed up the code to do /*< private >*/ ... stripping. + +1999-09-10 Martin Baulig <martin@home-of-linux.org> + + * gtkdoc.dsl.in ($generate-chapter-toc$): Return #t, not #f. + +1999-09-09 Martin Baulig <martin@home-of-linux.org> + + * gtkdoc-scan.in (ScanHeader): Don't force typedefs and other + things to start in column 0; allow some spaces in front of them. + Output `typedef struct { ... } name' structs as typedef, not as + structure. + +1999-09-08 Martin Baulig <martin@home-of-linux.org> + + * gtkdoc-mkdb.in (CreateValidSGMLID): `s/::/-/g;' for CORBA objects. + +1999-08-22 Erik Walthinsen <omega@cse.ogi.edu> + + * gtkdoc-scan.in: modified so it will find any Class, not just Gtk + and Gnome classes. Introduces the possibility of extraneous Class + definitions (verified), which should be pruned somehow (haven't + analyzed the false positive yet). + +1999-08-22 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtkdoc-mktmpl.in: + * gtkdoc-mkdb.in: a few fixes to ParseStructDeclaration. It still + has problems with nested structs/unions like those which occur in + gtkclist.h and gtktypeutils.h. + + * configure.in: removed gtk-doc.spec from AC_OUTPUT, as whoever wrote + this forgot to add gtk-doc.spec.in to CVS. + * Makefile.am: commented out gtk-doc.spec. + +Wed Aug 18 03:55:30 1999 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mktmpl.in: Propagate fix from gtkdoc-mkdb.in. + :-(; need to libraryize, need to libraryize. + +Wed Aug 18 03:55:30 1999 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mkdb.in: Fix bug that was preventing + structure field definitions from being output. + +Wed Aug 18 23:25:23 1999 Owen Taylor <otaylor@redhat.com> + + * configure.in: Add /usr/lib/sgml/stylesheet to list + of stylesheet directories. (Found in recent Debian + packages) + +1999-08-15 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtkdoc-mkdb.in: Output $decl_out as the struct rather than the + original $declaration. + +1999-08-12 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtkdoc-mkdb.in: + * gtkdoc-mktmpl.in: Added special case in ParseEnumDeclaration to + handle GIOCondition which uses strange macros like this: + typedef enum + { + G_IO_IN GLIB_SYSDEF_POLLIN, + ... + The GLIB_SYSDEF_POLLIN macro expands to something like '=1' + +1999-08-05 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtk-doc.dsl.in: output <br clear=all> after sections and at end of + page so that right-aligned images aren't messed up quite as much. + +Wed Aug 4 04:04:55 1999 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mk{db,tmpl}.in (ParseStructDeclaration): Allow + for bit fields. + + * gtkdoc-mktmpl.in (ReadObjectHierarchy): Remove + call to MakeXref that slipped in accidentally. + +Wed Aug 4 03:30:19 1999 Owen Taylor <otaylor@redhat.com> + + * doc/style-guide.txt: Removed references to creating + tables explicitly in favor of demonstrating new + syntax. Added a short section on /<* public >*/ + and /*< private *>/. + +Wed Aug 4 03:15:19 1999 Owen Taylor <otaylor@redhat.com> + + * gtkdoc-mktmpl.in gtkdoc-mkhtml.in: Handle Struct and + Enumerations in approximately the same way as we + handle parameters. That is, instead of (as before) + coding in the tables by hand, one uses lines like: + + @width: the width of the rectangle in pixels. + + To support migration from the older hand-coded + tables, if none of the members of a structure or + enumeration have a description in a @... line, then + we don't generate the table at all. + + Also, gtkdoc-mktmpl now loads up the object hierarchy, + because we need to be able to check if structures + are widget structures. + + In general, the coding here is pretty clean, though + the style is a little different. (I'm iterating + through strings with m/.../msg; instead of + s/^...//; for one thing.) However, there are a some + of FIXME's where I've whimped out on try to handle + real C syntax, and the need to split out and librarize + a bunch of duplicated code is greater than ever. + +1999-06-06 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * configure.in: updated version to 0.3. + + * doc/style-guide.txt: A couple of minor changes. + + * gtkdoc-mkdb.in: Get rid of a couple of messages. + Output an empty <para> if an Arg isn't documented, to keep Jade happy. + +1999-05-22 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtk-doc.dsl.in: Renamed %shade-verbatim-attr-2% to + $shade-verbatim-attr$ and removed our redefinition of + $verbatim-display$ since the stylesheets version now calls + $shade-verbatim-attr$ as a function which is just what we wanted. + + * README: Updated info on stylesheet versions supported - 1.40 is + known to be OK (with this version of gtk-doc), 1.19+ may work. + +1999-03-31 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * configure.in: update version to 0.2 for next release. + + * gtkdoc-mktmpl.in: + * gtkdoc-mkdb.in: added support for 'See Also' section. + + * gtk-doc.dsl.in: changed green background color slightly, and + set background color for enum tables. + +1999-03-21 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtkdoc-mkhtml.in (gtkdocdir): use '-w no-idref' to suppress all the + warnings about references to non-existent IDs. + +1999-03-18 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtkdoc-mkdb.in (OutputParamDescriptions): use role="params" for the + table so we can adjust the stylesheet code. + (OutputSGMLFile): Don't output 'one line description goes here'. + (ExpandAbbreviations): allow '-' in #symbol abbreviations, so we can + use #GtkWidget-struct. + (MakeXRef): get rid of special '-struct' suffix, for #GtkWidget-struct. + + * gtk-doc.dsl.in: use the "role" attribute on tables to set the + BGCOLOR. + + * gtkdoc-scan.in (ScanHeader): fix for scanning functions declared + over multiple lines - was catching things which weren't functions. + +1999-03-11 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * examples/gnomeui/Makefile.am (clean-local): + * examples/gnome/Makefile.am (clean-local): added *.args + + * gtkdoc-mkdb.in: added support for Args and variables. Also a few + minor changes in the output, e.g. don't show macros > 2 lines long. + + * gtkdoc-mktmpl.in: + * gtkdoc-scanobj.in: added support for Args. + + * gtkdoc-scan.in: added support for extern'ed variables. Also + accept 'extern' before function declarations. + + * gtk-doc.dsl.in: made output prettier. Changed the navigation bars + and the colours used for the various backgrounds. + + * doc/style-guide.txt: new file containinf a style guide for writing + the GTK+ documentation. + + * doc/README: added description of style-guide.txt + + * doc/setting-up.txt: fixed a typo + + * README: added a bit about Args. + +1999-02-07 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * Makefile.am: Removed all the scripts from EXTRA_DIST, as they are + now generated from the .in files which automatically go in the dist. + +1999-02-02 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * doc/setting-up.txt (scan): removed text which incorrectly said that + changing section titles means you have to recreate the main SGML file. + +1999-02-03 Sebastian Wilhelmi <wilhelmi@ira.uka.de> + + * configure.in: find perl in $PATH, generate the perl programs + from their *.in counterparts. + + * gtkdoc-fixxref, gtkdoc-mkdb, gtkdoc-mktmpl, gtkdoc-scan, + gtkdoc-scanobj: Renamed to *.in and changed /usr/bin/perl to + @PERL@, as determined by configure. + + * .cvsignore: Added diverse config* stuff and the new generated + perl programs. + +1999-01-28 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtk-doc.dsl.in: I forgot to make the new refentry code process the + child elements, so it was only outputting anchors for each page. + + * doc/setting-up.txt (scan): added step to create MODULE.types file + for modules which contain widgets (or objects). + + * gtkdoc-mkdb (OutputStruct): allow spaces inside the public/private + markers, e.g. "/* < public > */" + +1999-01-27 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * Makefile.am: added scripts to EXTRA_DIST and copied examples, doc + and db2man dirs in dist-hook. + + * doc/sections-file.txt: added a couple of examples. + + * doc/setting-up.txt: new document describing how to set up a module + to use gtk-doc. + + * doc/README: added description of setting-up.txt + + * README: added short 'Installation' section describing the + --with-dsssl-dir option. + + * gtk-doc.dsl.in: also output links to each RefEntry page in the + index.sgml file, so libgnomeui docs can link to widgets. (The widget + hierarchy links were not working before.) + +1999-01-26 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtkdoc-scan (ScanHeader): parse function declarations that have the + return type and name on one line, and the '(' and args on the next. + NOTE: functions with the start of the declaration split over 3 lines + will not be parsed (e.g. return type on one line, function name on + next, and '(' and first argument on the third.) I hope there aren't + any. + + * gtkdoc-mkdb (OutputStruct): Use a different SGML ID for widget + structs, since the original ID is used for the entire RefEntry. + Also only show parts of widget structs which are marked with a + comment '/*<public>*/'. Use '/*<private>*/' for private fields. + + * gtkdoc-mktmpl (UpdateTemplates): We include widget structs now, + so we do want warnings if they aren't used. + + * examples/gnomeui/gnomeui-docs.sgml: + * examples/gnomeui/gnomeui-sections.txt: + * examples/gnomeui/gnomeui.types: + * examples/gnome/gnome-docs.sgml: + * examples/gnome/gnome-sections.txt: sync with latest source. + + * examples/configure.in: Add --with-gnome-libs-dir option, so it can + be configured easily. + * examples/gnomeui/Makefile.am (DOC_SOURCE_DIR): + * examples/gnome/Makefile.am (DOC_SOURCE_DIR): use the new + GNOME_LIBS_DIR. + + * gtkdoc-mkdb (MergeSourceDocumentation): accept parameters names in + the source which use the wrong case, since there are quite a few of + these in Gnome. + +1999-01-25 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * gtkdoc-mktmpl: parse G_GNUC_EXTENSION before typedef'ed types. + + * gtkdoc-mkdb: added support for specifying include files in the + MODULE-sections.txt file, to be output at the top of the synopsis. + + * doc/sections-file.txt: added description of <INCLUDE> tag. + + * examples/gnomeui/gnomeui-sections.txt: + * examples/gnome/gnome-sections.txt: added use of <INCLUDE> + + * examples/configure.in: changed 'gtk-reference' to + 'gnome-libs-reference'. + +1999-01-18 Damon Chaplin <damon@karuna.freeserve.co.uk> + + * README: updated my email address & noted that version 1.15+ of the + DocBook modular stylesheets is needed (for $table-width$). + + * AUTHORS: updated my email address. + +1998-12-20 Jeff Garzik <jgarzik@pobox.com> + + * examples/gnomeui/gnomeui-docs.sgml, + examples/gnomeui/gnomeui-sections.txt, + examples/gnomeui/gnomeui.types: + s/gtkspell/gnome-spell/g + +1998-12-16 Damon Chaplin <DAChaplin@msn.com> + + * gtkdoc-mkdb (ExpandAbbreviations): Allow -ve contents, e.g. %-1. + (ScanSourceFile): Try to handle function descriptions that start + with 'Returns'. It was assuming that they were describing the return + value before. + Gets rid of 'Description:' which is sometimes included + at the start of the function description in the source comment blocks. + Makes sure newlines are preserved in the description, as consecutive + newlines are converted to paragraph separators later. + +1998-12-15 Damon Chaplin <DAChaplin@msn.com> + * Major changes to the scripts to merge in comments within source code + * gtk-doc-fixxref added + * examples directory added with an example for setting up modules to + use gtk-doc + * documentation updated + + +1998-11-28 Damon Chaplin <DAChaplin@msn.com> + + * gtkdoc-scanobj: + * gtkdoc-scan: + * gtkdoc-mktmpl: + * gtkdoc-mkdb: Major changes to make it easy to update the docs + when the API changes. It's pretty much all automatic now. + Also added licenses and function comments, and added 'use strict'. + The Gnome widgets should now be visible in the hierarchy. + Removed a few 'mkdir's which I don't think are necessary now. + +Tue Nov 24 16:32:23 1998 Owen Taylor <otaylor@redhat.com> + + * README doc/authors.txt: Updated to describe the + new generic scripts instead of the old ones hard-coded + for GLIB and GTK+. + +Tue Nov 24 01:06:17 1998 Owen Taylor <otaylor@redhat.com> + + * .cvsignore: Added .cvsignore + +Tue Nov 24 01:03:47 1998 Owen Taylor <otaylor@redhat.com> + + * autogen.sh configure.in: Minor touchups so the newly + imported stuff autogen's correctly. + diff --git a/gtk-doc-for-gtk4/HACKING b/gtk-doc-for-gtk4/HACKING new file mode 100644 index 0000000000..30f43fb0c5 --- /dev/null +++ b/gtk-doc-for-gtk4/HACKING @@ -0,0 +1,129 @@ +Testing +======= + +jhbuild --no-interact build 2>&1 | tee build.log +grep "gtkdoc-* line" build.log + +jhbuild buildone --no-net glib + +Since 1.23 we do have a snapshot feature to check the stability of the generated +xml/html. Simply run "make snapshot" under tests. Then make changes and run +"make check". The tests/sanity.sh will check for delta. If you want to inspect +what delta a change created, you can git checkout a revision before the change, +"make snapshot", go back to head and "make check", the sanity.sh test will now +fail and show the delta. + +Releasing +========= + +http://live.gnome.org/MaintainersCorner/Releasing + +'''shell +export OLD_VER=1.31 +export NEW_VER=1.32 +export OLD_VER_TAG=$(echo ${OLD_VER} | tr '.' '_') +export NEW_VER_TAG=$(echo ${NEW_VER} | tr '.' '_') +export GNOME_USER=... +``` + +- bump release date in: + help/manual/C/index.docbook +- bump version in (x.y.1 -> x.y+1) + configure.ac meson.build + +- update NEWS + # ./bugzilla.py general ${NEW_VER} gtk-doc >RELNOTES.txt + git log --summary --format=short GTK_DOC_${OLD_VER_TAG}.. >ChangeLog-${NEW_VER} + grep "Author:" ChangeLog-${NEW_VER} | sed 's/Author:\(.*\)\ <.*>/\1/' | sort | uniq >RELNOTES.txt + and then copy to NEWS + +```shell +# commit +git add configure.ac meson.build NEWS help/manual/C/index.docbook +git commit -m"release: update news and date in manual" +git push + +# dist +TAR_OPTIONS="--owner=root --group=root" make distcheck + +# tag +git tag -a GTK_DOC_${NEW_VER_TAG} -m"release: ${NEW_VER}" +git push origin GTK_DOC_${NEW_VER_TAG} + +# release +scp gtk-doc-${NEW_VER}.tar.xz ${GNOME_USER}@master.gnome.org: +scp NEWS ${GNOME_USER}@master.gnome.org:gtk-doc-${NEW_VER}.news +scp ChangeLog-${NEW_VER} ${GNOME_USER}@master.gnome.org:gtk-doc-${NEW_VER}.changes +ssh ${GNOME_USER}@master.gnome.org "ftpadmin install gtk-doc-${NEW_VER}.tar.xz" +``` + +- bump versions in: + configure.ac meson.build help/manual/C/index.docbook NEWS + +``'shell +# commit +git add configure.ac meson.build NEWS help/manual/C/index.docbook +git commit -m"release: bump versions and back to development" +git push +``` + +- update web-pages (gtk-web/gtk-doc) + git add gtk-doc/news.php + git commit -m"gtk-doc: new release (${NEW_VER})" + git push + +- if we want a icon on the newsfeed, we should copy a icon like on + http://ftp.acc.umu.se/pub/GNOME/sources/rhythmbox/rhythmbox.png + e.g. /usr/share/icons/hicolor/48x48/apps/devhelp.png + +Optimizing & Meassuring +======================= + +cd tests/gobject/docs/html +time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" ../../../../gtk-doc.xsl ../tester-docs.xml +~ 1.1 sec. +time saxon ../tester-docs.xml ../../../../gtk-doc.xsl gtkdoc.bookname="tester" gtkdoc.version="1.12" +~ 53 sec. +time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../tester-docs.xml +~ 0.7 sec + +cd /your/project/docs/html +time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "foo" --stringparam gtkdoc.version "1.12" /usr/share/gtk-doc/data/gtk-doc.xsl ../buzztrax-core-docs.xml +real 0m6.633s user 0m6.464s sys 0m0.128s +real 0m6.459s user 0m6.384s sys 0m0.068s + +time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "buzztrax-core" --stringparam gtkdoc.version "1.12" /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../buzztrax-core-docs.xml +real 0m3.312s user 0m3.224s sys 0m0.076s +real 0m3.549s user 0m3.464s sys 0m0.076s + + +xsltproc --profile data.xsl data.xml 2>report.txt +cat report.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o report.png + +one can now use "GTKDOC_PROFILE=1 make" to run this during gtkdoc-mkhtml. It +still needs a change in gprof2dot.py +https://bugzilla.gnome.org/show_bug.cgi?id=612186#c3 + +Performance tips: +* uses keys when we have slow xpath selects + http://www.xml.com/pub/a/2002/02/06/key-lookups.html + +Troubles with parsing regexps +============================= +Test regexps online: +http://www.solmetra.com/scripts/regex/index.php + +Test Coverage +============= +sudo apt-get install python3-coverage +PYTHONPATH=$PWD python3-coverage run tests/scan.py +python3-coverage html --include="gtkdoc/*.py" + +or + +cd test; make coverage + +Find Dead Code +============== +sudo pip3 install vulture +PYTHONPATH=$PWD vulture gtkdoc/*.py gtkdoc-*.in diff --git a/gtk-doc-for-gtk4/MAINTAINERS b/gtk-doc-for-gtk4/MAINTAINERS new file mode 100644 index 0000000000..fbc8f30367 --- /dev/null +++ b/gtk-doc-for-gtk4/MAINTAINERS @@ -0,0 +1,22 @@ +Stefan Sauer +Email: ensonic@hora-obscura.de +Userid: stefkost + +Damon Chaplin +Email: damon@gnome.org +Userid: damon + +Owen Taylor +Email: otaylor@redhat.com +Userid: otaylor + +Matthias Clasen +Email: mclasen@redhat.com +Userid: matthiasc + + +Note that several people are contributing to gtk-doc, and some parts of it +are technically maintained by other people. The people listed above are +meant as contacts for administrative questions. Other questions are best +directed to the mailing list gtk-doc-list@gnome.org. + diff --git a/gtk-doc-for-gtk4/Makefile.am b/gtk-doc-for-gtk4/Makefile.am new file mode 100644 index 0000000000..d7c7dbb1fa --- /dev/null +++ b/gtk-doc-for-gtk4/Makefile.am @@ -0,0 +1,151 @@ +## Process this file with automake to produce Makefile.in +ACLOCAL_AMFLAGS=-I m4 ${ACLOCAL_FLAGS} + +SUBDIRS = buildsystems/autotools buildsystems/cmake help tests + +bin_SCRIPTS = \ + gtkdoc-check \ + gtkdoc-depscan \ + gtkdoc-fixxref \ + gtkdoc-mkdb \ + gtkdoc-mkhtml \ + gtkdoc-mkhtml2 \ + gtkdoc-mkman \ + gtkdoc-mkpdf \ + gtkdoc-rebase \ + gtkdoc-scan \ + gtkdoc-scangobj + +gtkdocdatadir = $(datadir)/gtk-doc/data +gtkdocdata_DATA = \ + gtk-doc.xsl \ + version-greater-or-equal.xsl \ + devhelp2.xsd \ + devhelp2.xsl \ + style/home.png \ + style/left.png \ + style/left-insensitive.png \ + style/right.png \ + style/right-insensitive.png \ + style/up.png \ + style/up-insensitive.png \ + style/style.css + +pylibdatadir = $(datadir)/gtk-doc/python/gtkdoc +pylibdata_DATA = \ + gtkdoc/__init__.py \ + gtkdoc/check.py \ + gtkdoc/common.py \ + gtkdoc/config.py \ + gtkdoc/config_data.py \ + gtkdoc/fixxref.py \ + gtkdoc/highlight.py \ + gtkdoc/md_to_db.py \ + gtkdoc/mkdb.py \ + gtkdoc/mkhtml.py \ + gtkdoc/mkhtml2.py \ + gtkdoc/mkman.py \ + gtkdoc/mkpdf.py \ + gtkdoc/rebase.py \ + gtkdoc/scan.py \ + gtkdoc/scangobj.py + +pkgconfigdir = $(datadir)/pkgconfig +pkgconfig_DATA = gtk-doc.pc + +EXTRA_DIST = \ + MAINTAINERS \ + $(gtkdocdata_DATA) \ + $(pylibdata_DATA) \ + gtk-doc.pc.in \ + gtk-doc.doap \ + gtk-doc-fo.xsl \ + doc/README \ + doc/authors.txt \ + doc/gnome.txt \ + doc/sections-file.txt \ + doc/setting-up.txt \ + doc/style-guide.txt \ + examples/README \ + examples/Makefile.am \ + tools/docpercentages.pl \ + tools/gtk-doc.el \ + COPYING-DOCS + +CLEANFILES = \ + gtkdoc-checkc \ + gtkdoc-depscanc \ + gtkdoc-fixxrefc \ + gtkdoc-mkdbc \ + gtkdoc-mkhtmlc \ + gtkdoc-mkhtml2c \ + gtkdoc-mkmanc \ + gtkdoc-mkpdfc \ + gtkdoc-rebasec \ + gtkdoc-scangobjc \ + gtkdoc/__init__.pyc \ + gtkdoc/check.pyc \ + gtkdoc/common.pyc \ + gtkdoc/config.pyc \ + gtkdoc/fixxref.pyc \ + gtkdoc/md_to_db.pyc \ + gtkdoc/mkdb.pyc \ + gtkdoc/mkhtml.pyc \ + gtkdoc/mkhtml2.pyc \ + gtkdoc/mkman.pyc \ + gtkdoc/mkpdf.pyc \ + gtkdoc/rebase.pyc \ + gtkdoc/scan.pyc \ + gtkdoc/scangobj.pyc + +DISTCLEANFILES = \ + gtkdoc-check \ + gtkdoc-depscan \ + gtkdoc-fixxref \ + gtkdocize \ + gtkdoc-mkdb \ + gtkdoc-mkhtml \ + gtkdoc-mkhtml2 \ + gtkdoc-mkman \ + gtkdoc-mkpdf \ + gtk-doc.pc \ + gtkdoc-rebase \ + gtkdoc-scangobj \ + gtkdoc-scan \ + gtkdoc/config.py + +MAINTAINERCLEANFILES = \ + $(GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL) \ + $(GITIGNORE_MAINTAINERCLEANFILES_MAKEFILE_IN) \ + $(GITIGNORE_MAINTAINERCLEANFILES_M4_LIBTOOL) \ + INSTALL \ + RELNOTES.txt \ + ChangeLog-?.?? \ + gtk-doc-*.tar.xz \ + build-aux + +clean-local: + -find . -name "__pycache__" -type d -exec rm -r "{}" \; + +## We get warnings for left-over files when doing 'make distcheck' +distuninstallcheck_listfiles = find . -type f -print + +# Workaround for automake 1.61 +# https://lists.gnu.org/archive/html/bug-automake/2018-04/msg00002.html +distuninstallcheck_listfiles += | grep -v '__pycache__' + +-include $(top_srcdir)/git.mk + +dist-hook: + @if test -d "$(srcdir)/.git"; \ + then \ + echo Creating ChangeLog && \ + ( cd "$(top_srcdir)" && \ + echo '# Generated by Makefile. Do not edit.'; echo; \ + $(top_srcdir)/missing --run git log --stat ) > ChangeLog.tmp \ + && mv -f ChangeLog.tmp $(top_distdir)/ChangeLog \ + || ( rm -f ChangeLog.tmp ; \ + echo Failed to generate ChangeLog >&2 ); \ + else \ + echo A git clone is required to generate a ChangeLog >&2; \ + fi diff --git a/gtk-doc-for-gtk4/NEWS b/gtk-doc-for-gtk4/NEWS new file mode 100644 index 0000000000..41b80f9c94 --- /dev/null +++ b/gtk-doc-for-gtk4/NEWS @@ -0,0 +1,1076 @@ +GTK-Doc 1.32.1 (Aug 15 2019) +=============== + +Dev version + +This version does not generate object_index.sgml if the library contains no +gobjects. + + +GTK-Doc 1.32 (Aug 15 2019) +=============== + +Hotfix release. + +Contributors + + Michael Catanzaro + Stefan Sauer + +GTK-Doc 1.31 (Aug 5 2019) +=============== + +Nonmaintainer release to fix "Wrong permissions for style CSS file" (#84) + +Contributors + + Daniel Mustieles + Matthias Clasen + Michael Catanzaro + Nelson Benítez León + Stefan Sauer + Ting-Wei Lan + Xavier Claessens + +GTK-Doc 1.30 (May 08 2019) +=============== + +GTK-Doc is now using python-pygments to do the syntax highlighing. It is not +depending on highligh or source-highligh anymore. + +This version ships with a new expermiental gtkdoc-mkhtml2 toolchain replacing +gktdoc-mkhtml+gtkdoc-fixxref. + +Contributors + + Aleksander Morgado + Anders Jonsson + Andre Klapper + Bastien Nocera + Christian Kirbach + Corentin Noël + Daniel Mustieles + Emmanuele Bassi + Ignacio Casal Quinteiro + Lubomir Rintel + Marco Trevisan (Treviño) + Marek Cernocky + Mario Blättermann + Mathieu Bridon + Michael Catanzaro + Nicola Fontana + Philip Withnall + Piotr Drąg + Rafael Fontenelle + Stefan Sauer + Ting-Wei Lan + Руслан Ижбулатов + +GTK-Doc 1.29 (Aug 28 2018) +=============== + +GTK-Doc now requires python-3.X. It does not requires python-six anymore. + +Note that this is a nonmaintainer release and that tests are known to be broken. + + Changes + + o 674163 : html-build.stamp rule broken for out-of-tree builds with absolute paths + o 795744 : Too much escaped string - " & lt;child > " in description of " GtkOverlay as GtkBuildable " section + o 796011 : Crash in ScanDirectory caused by overlooked use of renamed `dir` variable + o 796012 : Several places in rebase.py incorrectly use `match.groups(1)` instead of `match.group(1)`, one causes a crash + + Contributors + + Adam Williamson + Anders Jonsson + Daniel Mustieles + David D + LRN + Marek Cernocky + Martin Blanchard + Michael Biebl + Michael Catanzaro + Rafael Fontenelle + Sebastian Geiger + Stefan Sauer + Tim Sabsch + + +GTK-Doc 1.28 (Mar 24 2018) +============== + +Bug fixes. + + Changes + + o 791928 : gtk-doc doesn't understand 'stability: Obsolete' + o 792148 : cmake: Installed GtkDocConfig.cmake has incorrect bindir path + o 792661 : use pygments to do syntax highlighting + o 793599 : Please run testsuite with V=0 + o 794051 : rebase: fix on-line location extraction from devhelp files + o 794182 : private_header regex is broken + + Contributors + + Anders Jonsson + Arnaud Rebillout + Behdad Esfahbod + Bruce Mitchener + Daniel Mustieles + Marek Černocký + Rafael Fontenelle + Stefan Sauer + Tim-Philipp Müller + Tim Sabsch + + +GTK-Doc 1.27 (Dec 07 2017) +============== + +Finetune the python port. + + Changes + + o 773879 : scangobj: Do not generate unused parameters + o 786174 : Several test failures on Arch Linux + o 787495 : gtkdoc-fixxref crashes when running vim for syntax highlighting + o 787768 : Aborts when glib2.0-dev is not installed + o 787862 : Always open files in text mode and always use utf-8 + o 788473 : fixxref crashes if a .devhelp2.gz file is found + o 789531 : Don't depend on the system shell + o 790022 : mkdb: Add support for (not optional) annotation + o 791131 : gtk-doc and python3: fixxref failures + + Contributors + + Alban Browaeys + Anders Jonsson + Christian Kirbach + Christoph Reiter + Daniel Mustieles + gkrithi8 + Jan Alexander Steffens (heftig) + Marek Cernocky + Michael Catanzaro + Pavel Grunt + Philip Withnall + Rafael Fontenelle + Simon McVittie + Stefan Sauer + Will Thompson + +GTK-Doc 1.26 (Aug 11 2017) +============ + +Remove tmpl support (gtkdoc-mktmpl). Port all tools from bash/perl to python. + + Changes + + o 773879 : scangobj: Do not generate unused parameters + o 780789 : Convert gtkdoc-scan from Perl to Python + o 752126 : Add support for inline program documentation + o 753052 : _() causes element a: validity error : ID idx already defined + o 758137 : GtkLabel and GtkShortcutsShortcut notes on escaping character entities don't render properly + o 764407 : Broken links to structs in function definitions + o 764543 : /usr/bin/gtkdoc-mkpdf always exits with an error + o 768675 : make check fails on master + o 769125 : gtkdoc-mkhtml/pdf fails on spaces in search path + o 769341 : gtkdoc-mkdb line 3966 triggers "Negative repeat count does nothing" warnings + o 771255 : "Symbol name not found at the start of comment block" warning with "attributes" annotation. + o 773151 : configure: Lower perl dependency to 5.16.0 + o 774168 : gobject introspection annotations and gtk-doc parser do not agree + o 774812 : Error messages from xsltproc are hidden by gtkdoc-mkhtml + o 778144 : Allow disabling introspection for ancillary property mechanisms + o 779566 : Replace shell executables with Python + + Contributors + + Anders Jonsson + Bernhard M. Wiedemann + Carlos Garcia Campos + Christian Kirbach + Daniel Mustieles + Emmanuele Bassi + Ernestas Kulik + HorimotoYasuhiro + Jussi Pakkanen + Kalev Lember + Marek Černocký + Mario Blättermann + Marius Vlad + Marvin Schmidt + Nirbheek Chauhan + Philip Withnall + Rafael Fontenelle + Sam Thursfield + Sebastian Rasmussen + Simon Josefsson + Stefan Sauer + Thomas Wood + Ting-Wei Lan + Tom Tryfonidis + Víctor Manuel Jáquez Leal + +GTK-Doc 1.25 (Mar 21 2016) +============== + + Changes + + o 763465 : –   released version of gtk-doc no longer understands cross-reference data in gtk+ + o 742404 : unify index.sgml and *.devhelp2 + change gtkdoc-fixxref to use *.devhelp2 + o 743182 : Automatically support PACKAGE variables as XML entities + o 744061 : Skip standard g_iface, parent_instance and parent_class struct members + o 751479 : help: Document the Stability tag for documentation comments + o 751777 : gtk-doc -sections.txt file documentation is a bit confusing + o 751783 : Creating master xml document documentation is a bit lacking + o 751906 : help: Fix incorrect example syntax for embedded images + o 752795 : documentation is not rebuilt when only content of doc comments change + o 753145 : gtkdoc-mkhtml fails on spaces in file names + o 753348 : gtkdocize does not handle -flat flavours + o 756297 : Add CMake module + o 756368 : gtkdocize mistakenly parses options from comments in configure.ac + o 756519 : `make check' fails - Sequence (?R...) not recognized in regex + o 756684 : Support (not nullable) annotation + o 756998 : Support |[ < !-- language= " plain " -- > ]| + o 758996 : gtkdoc-mkdb: ensure macros appear in the correct section + o 759017 : autogenerated ids in return and parameter blocks + + Contributors + + Christian Kirbach + Daniel Mustieles + Dimitris Spingos + Florian Brosch + Igor Gnatenko + Matthias Clasen + Philip Withnall + Quentin Glidic + Rafael Fontenelle + Sam Thursfield + Stefan Sauer + Thomas Wood + Tom Tryfonidis + Xavier Claessens + +GTK-Doc 1.24 (May 29 2015) +============ + + This is another quick bugfix release for a regression, see bug #749591 + + Changes + + o 749591 : gtk-doc 1.23 no longer includes xml namespace in .devhelp2 files + o 749706 : .gitignore files should not be under version control + o 749816 : Support syntax highlighting of different languages (patch included) + o 749901 : Strip common indent when highlighting with vim + + Contributors + + Daniel Mustieles + Dexter Chua + Michael Catanzaro + Peter De Wachter + Stefan Sauer + +GTK-Doc 1.23 (May 17 2015) +============ + + This is a quick bugfix release for a regression, see bug #749142. + + Changes + + o 749142 : Can't build totem-pl-parser from master using gtk-doc 1.22 + o 749210 : mkman: Use full URL to refer to the docbook manpages stylesheet + + Contributors + + Emanuele Aina + Stefan Sauer + +GTK-Doc 1.22 (May 07 2015) +============ + + Important notice - starting with the next release these long deprecated + features will be removed - you'll now see a warning if you actually use these + features. Please write to gtk-doc-list@gnome.org and tell us your concerns: + o gtkdoc-mktmpl - please move all the comments into the sources. + o generating html via sgml tools (jade/openjade), using xsltproc and + docbook-xslt is pretty common and preferred since version 1.6 + + Changes + + o 727778 : –   gtk-doc doesn't understand annotations for GList-contained types + o 729911 : Using #TypeName inshort_description makes " - " in HTML index disappear + o 732689 : strange result on a generated html page + o 734689 : " Specific - > General " document title format + o 736073 : Regression: problems with enum constants + o 736725 : Documentation consists mostly of empty space + o 741305 : Scanner issue with enum containing value ='{' + o 741763 : Example Makefile.am improvements + o 741941 : Last function argument missing in docs (possibly due to macro in code) + o 743879 : special case G_DECLARE_*_TYPE + o 743967 : Make build results reproducible + o 744075 : Missing struct members if forward declared in another header + o 744368 : gtkdoc-depscan doesn't handle unicode in .devhelp2 files correctly + o 746118 : gtkdoc-scan: fix regex for get_type() functions + o 746120 : Expand annotation recognition on symbol lines + o 746121 : gtkdoc-mkdb: don't warn on 'deprecated entities' + o 747207 : Typos in documentation + o 747298 : Test still tries to check gtkdoc-scanobj + o 748456 : xsl: Enable ToC generation on empty < toc/ > elements + + Contributors + + Anders Jonsson + Andre Klapper + Daniel Mustieles + David King + Dominique Leuenberger + Efstathios Iosifidis + Emanuele Aina + Fran Diéguez + Maria Mavridou + Marvin Schmidt + Olav Vitters + Philip Withnall + Rafael Ferreira + Ryan Lortie + Stefan Sauer + Tom Tryfonidis + Xavier Claessens + +GTK-Doc 1.21 (Jul 17 2014) +============ + + Important notice - starting with the next release these long deprecated + features will be removed, please write to gtk-doc-list@gnome.org and tell us + your concerns: + o gtkdoc-mktmpl - please move all the comments into the sources. + o generating html via sgml tools (jade/openjade), using xsltproc and + docbook-xslt is pretty common and preferred since version 1.6 + + Changes + + o 170860 : gtk-doc should have definitions for stability + o 644111 : one cannot specify against which libs gtkdoc-fixxref should resolve links (problematic with multiple versions) + o 657444 : " enum foo { ... } " ; not recognized + o 671519 : Self-test relies on nonportable (GNU enhanced) 'date' command + o 678094 : the word " returns " in a function description can be parsed as the " Returns: " section + o 722621 : gtk-doc tarball was created with 32bit uid/gid, unusable with mingw/msys tar + o 724739 : Self-test fail: gtkdoc-mkdb misusing perl datatype + o 725505 : new syntax highlighting for code is weird + o 725663 : configure: non POSIX test usage + o 730658 : Deprecation warning for non-deprecated type GParamFlags + o 730777 : Add support for nullable and optional annotations + + Contributors + + Christophe Fergeau + Damon Chaplin + Daniel Macks + Daniel Mustieles + Emmanuele Bassi + maria thukididu + Naohiro Aota + Philip Withnall + Rafael Ferreira + Stefan Sauer + Thomas Wood + William Jon McCann + +GTK-Doc 1.20 (Feb 16 2014) +============ + + Important notice - starting with the next release these long deprecated + features will be removed, please write to gtk-doc-list@gnome.org and tell us + your concerns: + o gtkdoc-scanobj (only used for gtkobject) + o return values need to be documented using "Returns:". We will remove the + heuristic that turns a paragraph starting with "Returns " into return docs. + o gtkdoc-mktmpl - please move all the comments into the sources. + o generating html via sgml tools (jade/openjade), using xsltproc and + docbook-xslt is pretty common and preferred since version 1.6 + + Changes + + o 605537 : Returns: listed among parameters + o 624001 : Support attribute-based method to deprecate symbols + o 662424 : Class hierarchy about interfaces not generated by default + o 665926 : should not have to document object structures + o 666509 : Specifying --enable-gtk-doc should not be required to build source packages + o 669417 : Duplicate IDs generated for unions registered as boxed types + o 671519 : Self-test relies on nonportable (GNU enhanced) 'date' command + o 692367 : gtkdocize should take a srcdir argument + o 696570 : style updates + o 697940 : Race condition between setup-build.stamp and scan-build.stamp + o 701259 : /bin/bash: -chmod: command not found + o 701638 : Support automake parallel test harness (fix error with GTKDOC_CHECK) + o 706404 : Minor bug in gtkdoc-mkdb + o 706438 : Empty lines added at the beginning and at the end of a programlisting + o 707426 : master is broken in picking up flavour from configure.ac + o 707717 : Support " Deprecated: X.Y " + o 708268 : New *-insensitive.png files are not distributes + o 710478 : gtkdoc-mkdb: Don't complain about annotations with hyphen + o 711111 : gtkdoc-mkdb: sort entries in the glossary + o 711598 : gtkdoc-scan doesn't ignore decorators containing parentheses + o 719644 : docs: make yelp usage conditional in manual + o 719645 : configure: emit message when looking for yelp + o 720061 : make: create subdirectories of the content_files to the builddir + o 721228 : configure: search for xml catalog in XDG_DATA_DIRS + o 722479 : cp -u is not portable + o 723118 : Mark |[ blocks as CDATA + o 723288 : Fix MarkDown support + o 723417 : New MarkDown parser + o 723696 : Add support for blockquote + o 723812 : Add support for reference links + o 723913 : List in markdown: < p > inside the last element of a < ul > list + o 723991 : Improve the display of the synopsis + o 724002 : gtkdoc-scan: Fix use of uninitialised value in trace logging + + Contributors + + Alban Browaeys + Alexander Kanavin + Carlos Garcia Campos + Christian Kirbach + Daniel Mustieles + David King + David Nečas + Dieter Verfaillie + Dimitris Spingos + Hib Eris + Matthias Clasen + Philip Chimento + Philip Withnall + Rafael Ferreira + Rico Tzschichholz + Ryan Lortie + Sebastian Rasmussen + Sébastien Wilmet + Stefan Sauer + Stef Walter + William Jon McCann + Zbigniew Jędrzejewski-Szmek + +GTK-Doc 1.19 (Jun 05 2013) +============ + + Changes + + o 652740 : Warnings during expansion of content files + o 660436 : Warning for skip annotations on function parameters + o 661853 : allow EXTRA_DIST to be predefined + o 668228 : several of the tests use syntax not compatible with traditional Bourne shells + o 670724 : gtk-doc.make: double recursion when maintainer-clean + o 670767 : generated file gnome-doc-utils.m4 is in version control + o 670796 : (patch) Show commands when building documentation with make + o 671519 : Self-test relies on nonportable (GNU enhanced) 'date' command + o 671960 : make dist fails without html/* + o 672710 : Use new documentation infrastructure + o 676685 : Allow to order functions without using $MODULE-sections.txt + o 685365 : (PATCH) Fix contents of warning message, should be " -sections.txt " not " -section.txt " + o 686148 : [patch] suggested parameters for gtkdoc-scangobj + o 687685 : 'g_type_init' is deprecated + o 688204 : undocumented enum values missing in indexes + o 688423 : Add support for " transfer floating " introspection annotation + o 689209 : Automake complains about trailing space after backslash. + o 690438 : Small improvements + o 696930 : Incorrect allowed value for a property + o 700981 : make: copy the files with their relative path included + + Contributors + + Alban Browaeys + Aleksander Morgado + Alexandre Franke + Bruno Brouard + Colin Walters + Daiki Ueno + Daniel Mustieles + David King + David Nečas + Dieter Verfaillie + Dimitris Spingos + dmustieles + Henrik Stokseth + Hib Eris + Javier Jardón + Jens Georg + Jiro Matsuzawa + Krzesimir Nowak + Mario Blättermann + Martin Pitt + Matthias Clasen + Murray Cumming + Piotr Drąg + Ryan Lortie + Sébastien Wilmet + Simon Josefsson + Stefan Sauer + Stef Walter + Takao Fujiwara + Tim Mooney + Tom Tryfonidis + 黄世海 + + +GTK-Doc 1.18 (Sep 14 2011) +============ + + o gtk-doc supports a subset of markdown (headings and lists) - see + http://git.gnome.org/browse/gtk-doc/tree/tests/gobject/src/gobject.c + o gtk-doc does not generate old devhelp files any more. This cuts down doc + generation time and works for devhelp >=0.11 (was released in 2005). + o changes for out-of-source dir build caused breakage for projects using + DOC_SOURCE_DIR with a relative path (to builddir). It is recommended to use + DOC_SOURCE_DIR=$(top_srcdir)/src/xxx. + + Changes + + o 590927 : Support AM_SILENT_RULES for doc-build steps + o 617121 : /* < private > */ declarations in enums are still displayed + o 627758 : A way to ignore a symbol + o 639145 : shorthand syntax for headings + o 644291 : Enum parser breaks on assignment of ')' + o 646870 : HTML_IMAGES no longer in EXTRA_DIST + o 648289 : gtkdoc-mkdb doesn't compile. + o 648331 : Specify compatible options for 'highlight' consistently. + o 649269 : gtkdoc-scanobj should set some of its own CFLAGS/LDFLAGS + o 650407 : Buildings docs while distchecking produces thousands of “No declaration found” warnings, then fails. + o 652746 : Documentation of plain boxed structs broken + o 652764 : Update autotools config a bit + o 655711 : summarize depscan output by package + o 656453 : Performance improvements (PATCH) + o 656658 : gtk-doc.make: install target doesn't install docs when building in a separate directory + o 656773 : gtk-doc fails to find a symbol declared as 'char* const' + o 656946 : gtk-doc unable to handle 'extern short int' + o 657377 : srcdir!=builddir builds discard contents of tmpl + + Contributors + + Bakaoukas Nikolaos + Claude Paroz + Daniel Mustieles + David Necas + David Nečas + Javier Jardón + Jorge González + Mario Blättermann + Matthias Clasen + Michał Górny + Shaun McCance + Stefan Sauer (Kost) + Will Thompson + Yaakov Selkowitz + + +GTK-Doc 1.17 (Feb 16 2011) +============ + + Changes + + o 127049 : building reference documentation fails when builddir != srcdir + o 640241 : non-srcdir builds busted + + Contributors + + Daniel Mustieles + Javier Jardón + Stefan Kost + +GTK-Doc 1.16 (Jan 14 2011) +============ + + o gtkdoc-check can do more checks, one might need to update Makefile.am from + the examples/Makefile.am + + Changes + + o 625776 : serialise doubles and floats always with a decimal dot + o 627269 : link to signalflags docs from signal descriptions + o 467488 : GTK+ man pages request + o 481811 : Inline function bodies are confused with declarations + o 501107 : EXTRA_DIST automake warnings + o 512565 : add GTK_DOC_IGNORE + o 518427 : documentation best pratices needed + o 597937 : Function pointers as parameters to other functions are parsed improperly + o 612028 : gtkdoc-fixxref should call /usr/bin/vim -n -e -u NONE -T xterm + o 617478 : Tooltip is a nuisance + o 618379 : Navigation is hiding anchors title + o 620249 : invalid xml for object_index with (n_objects % 3) == 0 + o 621931 : support GType and GVariant types + o 622971 : List of typos in the GTK-doc manual + o 623777 : G_TYPE_STRV in signals generate wrong docs + o 623968 : gtkdoc-mkdb generates invalid xml from sgml in inline comments + o 624199 : parser picks up contents of large macros + o 624200 : 'const' confuses the parser + o 627223 : gtkdoc-fixxref vim highlight fails on xhtml suffix + o 627920 : `make check` rule to list xml files missing from DOC_MAIN_SGML_FILE + o 628611 : gtk-doc > = 1.13 creates automagic dependencies on syntax highlighters + o 628794 : Issue in gtkdoc-mkman.in + o 630288 : Fix 'scope notified' annotation + o 631336 : remove lists of gtk+ signal args in gtkdoc-scanobj and -scangobj + o 632587 : gtkdoc-scanner fails to identify (closure) annotation + o 638330 : const in parameter list is ignored + o 638831 : Support GTK+ 3 cell properties + + Contributors + + Bruno Brouard + Christian Persch + Claude Paroz + Gilles Dartiguelongue + Javier Jardón + Jorge González + Maarten Bosmans + Mario Blättermann + Matej Urbančič + Matthias Clasen + Pablo Castellano + P. F. Chimento + Philip Withnall + Rodrigo Aliste + Simón Pena + Stefan Kost + Tim-Philipp Müller + Vasilis Tsivikis + +GTK-Doc 1.15 (May 21 2010) +============ + + Changes + + o 614496 : Support for multiple DOC_SOURCE_DIR directories + o 615550 : gtk-doc fails to recognize (scope ...) and (skip) annotations + + Contributors + + Andreas Rottmann + Jorge González + Nicola Fontana + Nikos Bakaoukas + Stefan Kost + +GTK-Doc 1.14 (Mar 28 2010) +============ + + Changes + + o 593282 : Append " _struct " prefix to every struct name + o 599514 : sane support for per-page images + o 604892 : checks fail + o 613611 : parameter descriptions with annotations truncated at first \n + o 115531 : add short description to index entries + o 165425 : gtk-doc fails to parse unions + o 512155 : gets confused by multiline typedef + o 568711 : undocumented enum values are not reported + o 590602 : secondly running gtkdoc-mkdb will generate DOCTYPE missing XML files + o 590625 : $(DOC_MODULE)-overrides.txt is required by " make dist " + o 591975 : Section_Id always embeds a trailing newline + o 604885 : Fix the use of gtkdocize --flavour option + o 604992 : gtkdoc-fixxref broken link warning is broken for functions + o 604995 : Syntax error in gtkdoc-mkman + o 604998 : Check for syntax errors in the test suite + o 605052 : put class structs to the generated section file + o 605211 : Many build failures with gtk-doc 1.13 + o 605281 : Add " Since " and " Deprecated " tag to function example + o 605285 : Add < keycap > and < keycombo > example + o 605289 : Some documentation improvements + o 605452 : Added more info to " Documenting symbols " sectio + o 605564 : Env var equivalent to --flavour=no-tmpl + o 606661 : XInclude error while gnerating documentation + o 607445 : gtk-doc does not support long double as returned value type + o 607531 : Execute system() calls in subshells to ease debugging + o 609062 : [All-langs] [gtk-doc] Translated *.po files not available within ~/po directory + o 609194 : sort interface implementers + o 610255 : Self-test failure in git as of 2010-02-17: FAIL: gobject.sh + o 610257 : Patch to make GTK-DOC notice functions/variables with 'signed' prototypes + o 611848 : gtk-doc produces invalid DocBook markup if the SECTION ends with a tag that cannot be nested inside < para > + + Contributors + + Bruno Brouard + David Nečas + Emilio Pozuelo Monfort + Francisco Javier F. Serrador + Javier Jardón + Jorge González + Loïc Minier + Mario Blättermann + Marios Zindilis + Nicola Fontana + Philip Chimento + Runa Bhattacharjee + Ryan Lortie + Simon Josefsson + Simon McVittie + Stefan Kost + Sweta Kothari + Vincent Untz + Felix Iyadurai + krishnababu k + +GTK-Doc 1.13 (Dec 18 2009) +============ + + o 604891 : gtk-doc tarball does not build + + Contributors + + Stefan Kost + +GTK-Doc 1.12 (Dec 18 2009) +============ + + Changes + + o 591450 : Build related fixes + o 466535 : generate documentation as pdf + o 502191 : acronym support + o 532395 : inline function parsing problems (e.g. in glib api docs) + o 536928 : have syntax highlghted and xrefs source code samples + o 562064 : index generation trouble + o 562310 : glib 2.18.3: /bin/sh: line 1: gtkdoc-rebase: command not found + o 562655 : doesn't produce deprecation note for signals + o 565126 : linking to struct members + o 565835 : Three spelling errors in gtk-doc-manual + o 566911 : add support for --help and --version to remaining tools + o 567132 : Take FOO_GET_INTERFACE as standard + o 568702 : gtkdoc-mkhtml no longer works when symlinked + o 568706 : gtkdoc-scan: use CamelCase id for interfaces + o 568708 : gtkdoc-scan should try not to scan files twice + o 568714 : Perl errors when syntax highlighting is not available + o 568732 : missing long descriptions undetected + o 568734 : configure check for gtk-doc prints that gtk-doc cannot be built + o 569339 : abbreviation are not expanded at the start of text + o 572396 : Fix to use shave + gtk-doc + libtool 1.x + o 572612 : Mistakenly substitute -1 with G_MAXULONG in x86_64 + o 572967 : use g_strerror + o 574654 : --ignore-decorators does not ignore trailing stuff + o 575574 : Be more friendly for files with a space in their name + o 575623 : Update FSF address + o 575711 : < table > element mismatch in highlighted code + o 576313 : implicit declarations in testsuite ? + o 577059 : Gnome-doc support can't be disabled + o 577774 : Test suite run even when built with --disable-gtk-doc + o 580206 : gcc warnings in < module > -scan.c + o 580300 : gtkdoc-scan picks up _get_type functions it should not + o 580622 : xml dir is both part of distclean and dist rules + o 581237 : gtk-doc uses wrong gtkdoc-check in " make check " phase + o 584952 : " uninitialized value in concatenation " gtkdoc-mkdb line 938 + o 587103 : return values of function-like macros + o 587196 : Typo in a string + o 589426 : Python is a required dependency + o 591789 : master FTBFS with automake 1.11 + o 594224 : Please fix manual about inlined SECTION comments (and show warnings when invalid) + o 596730 : Signed vs. unsigned comparison in gtkdoc-scangobj.in causing compile errors + o 596731 : autogen.sh doesn't recognize automake-1.11 + o 602026 : Warn if non-existing function gets referenced + o 602518 : Doesn't support " long int " return type + o 604798 : tests/fail.sh and tests/tools.sh.in use bashisms + + Contributors + + Claude Paroz + Dan Williams + Daniel Mustieles + Daniel Nylander + H. Habighorst + Jannis Pohlmann + Javier Jardón + Jennie Petoumenou + Jorge González + Mario Blättermann + Nicola Fontana + Philip Chimento + Philip Withnall + Simos Xenitellis + Stefan Kost + Sven Herzberg + + +GTK-Doc 1.11 (Nov 16 2008) +============ + + Changes + + o 531572 : one-page generation option + o 448879 : Use a footer when generating HTML documentation + o 311857 : xsltproc very slow generating index for gtk-docs.sgml + o 335239 : Using gnome-doc-utils for gtk-doc documentation + o 460753 : enable vpath build in gtkdoc-mkhtml + o 473342 : Warn about repeated symbols in sections + o 487727 : DocBook XML DTD version + o 523669 : make check: Element publisher content does not follow the... + o 530758 : gtk-doc should not expand XML tags and their attributes + o 533262 : no-template mode scans different source files + o 534627 : gtk-doc uses non-standard HTML element + o 542137 : No declaration found for: gsf_output_* + o 543855 : Fix for Bug 460753 (enable vpath build in gtkdoc-mkhtml) ... + o 544172 : Fails to parse return value of 'char const *' + o 552822 : Add rules to create $(REPORT_FILES) + o 553407 : Example Makefile.am uses obsolete INCLUDES instead of AM_... + o 554718 : gtk-doc needs to allow versioned TARGET_DIR + o 554833 : Be more careful with " struct _ < struct_name > " + o 558082 : evince docs build fails with GTK_DISABLE_SINGLE_INCLUDES + o 559281 : Correct check for existence of gtkdoc-rebase + + Contributors + + Behdad Esfahbod + Christian Persch + David Nečas + Felix Riemann + Jeffrey Stedfast + Marc-Andre Lureau + Matthew Barnes + Peter Kjellerstedt + Sebastian Dröge + Simon Josefsson + Stefan Kost + + +GTK-Doc 1.10 (Mar 20 2008) +============ + + Changes + + o 460753 : enable vpath build in gtkdoc-mkhtml + o 503119 : Add dependency on content_files to SGML target + o 127049 : building reference documentation fails when builddir != s... + o 481811 : Inline function bodies are confused with declarations + o 448879 : Use a footer when generating HTML documentation + o 492005 : Deprecation guard warnings for properties and signals + o 498521 : Inconsistent compiler flags passed in gtk-doc.make + o 365913 : gtk-doc output is not predictable + o 446648 : gtk-doc does not handle forward typedef'd enums + o 468278 : Display proper types for properties + o 497367 : don't use US-ASCII for output encoding + o 501066 : Missing quotes around gtkdoc-rebase check cause a warning + o 508897 : [PATCH] Fix build when gtk-doc is not installed + o 509539 : Building documentation aborts when no .types file is present + o 512154 : Struct member type attributes are limited to one token + o 513318 : gtk-doc.el doesn't work fine with emacs22 + + Contributors + + Benjamin Otte + Carlos Garnacho + Damon Chaplin + David Nečas + Frederic Peters + Joe Marcus Clarke + Kouhei Sutou + Loïc Minier + Mathias Hasselmann + Petteri Räty + Rouslan Solomakhin + Stefan Kost + Sven Herzberg + Yeti + + +GTK-Doc 1.9 (Sep 30 2007) +=========== + + Changes + + o 419308 : unsynced regexps for parameter parsing + o 449618 : Top navigation bar is in the way + o 453717 : fixxref logic to determine absolute path's is flawed + o 457173 : unit tests for gtk-doc + o 465920 : Use gtkdoc-rebase + o 467773 : default master doc should have proper extension + o 141869 : Poor error generated when faced with a type declared as '... + o 156643 : Avoid make error in gtk-doc.make + o 322035 : wrong macro parsing + o 323938 : gtk-doc.m4 check is silent + o 324535 : gtk-doc doesn't handle deprecation inside enumerations + o 355352 : If you don't have an instantiatable type for a gtypeinter... + o 379466 : Improve C parser to handle TYPE\nVARIABLE in function pro... + o 380824 : docs are truncated if line begins with '* returns ' + o 383456 : ' make check ' test for 100% documentation + o 411739 : Gtk-doc fails to handle ' struct tm * function_name (); ' + o 415388 : Please clean -undocumented.txt files + o 418027 : gtkdoc-mkdb does not handle #ifdef in enum {} + o 419997 : parameter name trouble + o 428596 : Warnings with gtk-doc.m4 macros + o 434134 : fixxrefs like sed for installing pregenerated docs + o 436565 : Report undeclared symbols into a file + o 445596 : Impossible to link a page with an anchor + o 445693 : Does not understand ' unsigned long ' as a type + o 450338 : Make gtk-doc.m4 fail when needed gtk-doc is not installed + o 454916 : gtk-doc should permit generation of URI-based cross-refer... + o 457077 : add --no-implicit-returns to gtkdoc-mkdb + o 459225 : Accept automake-1.10 in autogen.sh + o 459725 : ' jhbuild build gtk-doc ' fails on make + o 460127 : parsing nested union/structs confuses public/private state + o 465365 : [PATCH] gtk-doc does not compile + o 466559 : [CSS] styling <hr />; + o 471014 : G_CONST_RETURN * G_CONST_RETURN * function not picked up + o 477532 : function variables + o 479913 : gtk-doc.notmpl.make is not distributed + o 479923 : distclean test output properly + + Contributors + + Benjamin Otte + Damon Chaplin + David Nečas + Frederic Peters + Loic Minier + Petteri Räty + Rouslan Solomakhin + Stefan Kost + Sven Herzberg + Yeti + + +GTK-Doc 1.8 (Feb 16 2007) +=========== + + o Made it easier to include example code in the source code comment blocks. + "|[ ... ]|" can be used to delineate example code (it just gets converted + to "<informalexample><programlisting>"), and most of the text in example + code is left as it is. The only thing that is still expanded is + '#' to allow links to a symbol's documentation, e.g. '#GtkWidget'. + o Made the field widths wider for the HTML output, so it looks a bit nicer. + o Added a '--rebuild-sections' option to gtkdoc-scan to automatically rebuild + the MODULE-sections.txt file. This only works if all the header files are + organized neatly and functions don't need rearranging in the docs. + o Added a '--rebuild-types' option to gtkdoc-scan to automatically rebuild + the MODULE.types file, so you don't need to add new types manually. + o Leave CDATA sections as they are, in the extra XML content files and within + source code comment blocks. + o Allow the section id and #include's to be set within the "SECTION:" comment + block, using "@Section_ID:xxx" and "@Include:". + o Added "--default-includes" option to specify the default #include's (for + people who are using --rebuild-sections and so can't specify it in + MODULE-sections.txt). + o Added a '--query-child-properties' argument to help document child + properties of arbitrary GObjects (used by things like canvas widgets). + o Fixed documentation of signals of interfaces. + + +GTK-Doc 1.7 (Jul 29 2006) +=========== + + o Fixed bug that resulted in empty "@:" lines in the templates. + o Fixed a few bugs with the XSL code. + o Supported a few more variations of C syntax. + o Remove the internally-used '-struct' suffix from links to widget structs. + o Fixed a few missing build dependencies. + o Added a new "C-x4s" binding to the emacs lisp code, to insert a blank + section header in the source code. + o Fixed bug that ignored inline section header docs with '-' in their names. + o Added a 'make docs' target that can be used to build the docs even when + gtk-doc has been disabled at configure time. + + +GTK-Doc 1.6 (Apr 9 2006) +=========== + + o Removed the hard dependency on openjade or jade, since XML is used mainly + now rather than SGML. + o Install the .pc file in $(datadir) rather than $(libdir) since gtk-doc is + architecture-independant. + o Added "--ignore-decorators" option to ignore a list of declarators in + function declarations. + o Support '#Object::signal'/'#Object:property' to link to signals/properties + o Fixed missing index terms. + + +GTK-Doc 1.5 (Mar 7 2006) +=========== + + o Output the new version of devhelp2 information, but still generate the old + devhelp files so older versions of DevHelp still work OK. + o Fixed the initial creation of the *-sections.txt file so the object + hierarchy, signals and properties all work automatically. + o Show information about signal flags (run first/last). + o Support a --source-suffixes argument specifying which source files to scan. + o Support other root object types besides GObject and GInterface. + o Use a fixed navigation bar for the generated documentation. + o New documentation from Stefan Kost. + o Handle more variations of C syntax. + + +GTK-Doc 1.4 (Jul 3 2005) +=========== + + o Support section documentation (title, short description, long description + and 'see also') within the source code. I think everything can now be + documented within the source code. + o Support Stable/Unstable/Private stability levels for everything. + + +GTK-Doc 1.3 (Jan 9 2005) +=========== + + o Use the new style.css stylesheet instead of hard-wiring the styles. + o Updated the documentation and example build files. + o Added support for a gallery of widget images. + o Output default values for widget properties and allowed ranges. + o Only underline links in the docs when the mouse hovers over them. + o Added support for placing the parameter table anywhere within the function + documentation (using the "<!--PARAMETERS-->" marker). + o Handle more variations of C syntax. + + +GTK-Doc 1.2 (Feb 16 2004) +=========== + + o Added widget signals and properties to undocumented output and statistics. + o Added support for an index of all symbols. + o Emit "Since:" information for signals and properties. + o Added derived subclasses and interfaces to the widget hierarchies. + o Added .cat SGML catalog file. + o Support properties on interfaces. + o Added "--help" options to the scripts. + + +GTK-Doc 1.1 (Apr 18 2003) +=========== + + o Add a gtk-doc.m4 macro that allows packages to provide consistent + checking for gtk-doc. + o Check to make sure that the XML catalog actually contains entries + for the DocBook XML DTD and XSLT stylesheets. Please consult the + README file if your system's XML catalog isn't set up. + o Add infrastructure for including the standard gtk-doc makefile + glue, so that maintainers of packages don't need to worry about + keeping it up to date. See glib head for an example of its use. + o Some updates to the devhelp contents file generation, as suggested + by Hallski. + o Fix some bugs in the DocBook XML codepath that were preventing + inter-module cross references from being resolved. + o Fix some bugs in extraction of object property documentation. + + +GTK-Doc 1.0 (Jan 20 2003) +=========== + + o Added support for "Since:" and "Deprecated:" tags, and look for deprecated + guard macros in header files. + o Support /*< public >*/ and /*< private >*/ markers for all structs. + o New "--ignore-files" option for gtkdoc-mkdb, to ignore files or directories. + o Used the "sgml-raw" output type with openjade, to avoid problems with Lynx. + o Added .pc pkg-config file which can be used to check the gtk-doc version. + + +GTK-Doc 0.10 (Nov 14 2002) +============ + + o --output-format option to select whether SGML or XML is generated. + o Use openjade or jade when converting SGML to HTML. + o Use xsltproc to convert XML to HTML, with a new look. + o In XML mode, support XIncludes as an alternative to entities. + o In XML mode, create .devhelp files. + o List interfaces in the object hierarchy. + o Create docs for signals on interfaces. + o Generate links between interface and their implementations and + prerequisites. + o Create docs for child and style properties. + o Use blurbs for property documentation. + o Allow inline documentation for signals and properties. diff --git a/gtk-doc-for-gtk4/README b/gtk-doc-for-gtk4/README new file mode 100644 index 0000000000..0a0b031c98 --- /dev/null +++ b/gtk-doc-for-gtk4/README @@ -0,0 +1,112 @@ + +GTK+ DocBook Documentation Generator +==================================== + +GTK-Doc is used to document C code. It is typically used to document the public +API of libraries, such as the GTK+ and GNOME libraries, but it can also be +used to document application code. + +Note that GTK-Doc wasn't originally intended to be a general-purpose +documentation tool, so it can be a bit awkward to setup and use. +For a more polished general-purpose documentation tool you may want to look +at Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code +to document the signals and properties of GTK+ widgets and GObject classes +which other tools may not have. + +From your source code comments GTK-Doc generates a Docbook XML document, which +is then transformed into HTML and/or PDF. +The generated HTML documentation can be browsed in an ordinary web browser or +by using the special Devhelp API browser +(see https://wiki.gnome.org/Apps/Devhelp). + + +Requirements +============ + +Python 3.x + http:///www.python.org + +Additional python modules: + For the tests: unittest, parameterized + For mkhtml2 (experimental): anytree, lxml and pygments + For fixxref: pygments + +For XML output (recommended): + +The DocBook XML DTD. + http://www.oasis-open.org/docbook/ + +The DocBook XSL Stylesheets. + http://docbook.sourceforge.net/projects/xsl/ + +libxslt & libxml2 >= 2.3.6. + http://xmlsoft.org/ + +For PDF output: + +the dblatex tool. + http://dblatex.sourceforge.net/ + +Most distributions now have packages for all of these, so I would strongly +advise that you grab those. + +See the documentation in the help/manual directory for more information. You can +read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml + + +Building +======== + +We are supporting two build systems to build gtk-doc for some transitions time. + + +Build using auto* +----------------- + +In order to build with a the classic auto* system use these commands: + +Build from git: +./autogen.sh; make + +Build from dist tarball: +./configure; make + +There are a few parameters one can pass to ./configure, run ./configure --help +to see them. Also ./autogen.sh can take those settings (and will hand them +through to ./configure). + +To run the tests: +make check + +To install: +make install + +To make a release: +make distcheck +or +make dist + + +Build using meson +----------------- + +Support for meson is new and still experiemntal. + +Build it from git: +meson build . +ninja -C build + +There are some options one can specify too: +meson build . --prefix= +meson build . -Dautotools_support=false +meson build . -Dcmake_support=false +meson build . -Dyelp_manual=false + +To run tests: +ninja -C build test + +To install: +ninja -C build install + +To make a release: +ninja -C build dist diff --git a/gtk-doc-for-gtk4/TODO b/gtk-doc-for-gtk4/TODO new file mode 100644 index 0000000000..05d85d3324 --- /dev/null +++ b/gtk-doc-for-gtk4/TODO @@ -0,0 +1,483 @@ +The TODO list for the gtk-doc project is at Bugzilla, +the bugtracking system of the GNOME project. + +Visit + http://bugzilla.gnome.org/buglist.cgi?product=gtk-doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED +to see what is already requested, or where you can help. :-) + +To put an other request on the TODO list, visit + http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc + +Also have a look at + http://live.gnome.org/DocumentationProject/GtkDocFuture +and join discussion about future features. + + +Developers can also add items here :) + += Less files to manually edit = +The goal is that we configure gtk-doc in configure.ac and Makefile.am and +document the code in the sources. Right no we also have to edit a bunch of extra +files: + * $(DOC_MODULE).types + * $(DOC_MODULE)-docs.xml + * $(DOC_MODULE)-sections.txt + +== .types == + +* using SCAN_OPTION="--rebuild-types" can be used to avoid maintaining the types + file +* we need to check if this works well for all kind of _types (e.g. boxed) + https://bugzilla.gnome.org/show_bug.cgi?id=605025 + +== -section.txt == +https://bugzilla.gnome.org/show_bug.cgi?id=646094 + +* using SCAN_OPTION="--rebuild-sections" can be used to use the audogenerated + sections file +* when scanning a header file, everything of the header and the respective .c + file will be put to one section +* symbols can be hidden using __GTK_DOC_IGNORE__ + +* we need comment markup to override the section + e.g.: " * InSection: xxxx" + this needs gtkdoc-mkdb::ScanSourceFile to understand a new tag, which + otherwise would appear as verbatim in the sources +* if one has "@InSection: xxxx" in a section comment we could patch the + main.xml file and insert then xi:include line (would possibly rely on a + special comment-pair there, we might also need to rewrite these + auto-generated xi:includes every time as the placements could have been + changed, or we have a xi:include for each chapter, that we regenerate). +* we need a way to specify subsections (Standard, Private) + this could be done in the SECTION comment + e.g.: "@HideSymbols: <list-of-symbols-to-hide> + * we could allow to have a SUBSECTION:xxx comment block too + but then we list all the symbols here to override the auto-section placement +* if we want to avoid the "InSection in symbol docs we could also have + e.g.: "@ExtraSymbols: <list-of-symbols-to-include> +* documented symbols that are in a file without section comment and do not + appear in "@ExtraSymbols", "@HideSymbols" would go to unused.txt + * shall we deprecated the unused sub-sections? +* can we have both at the same time (for migration) + * yes, read section-file first and add/override from inline comments + + += More abbreviations = +* expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations) + + += Running = +gtk-doc is using a makefile with several targets to get from sources to docs. It +uses makefile variables for configuration. +It might be easier to have a gtkdoc tool that can run the other gtkdoc tools +in the right order (ev. by importing them as modules). This could handle a few +things nicer that the makefiles don't do well. This would also make it easy to +run it manually or integrate into other build systems. + + += Intermediate files = +Can we change the intermediate files into e.g. json or yaml so that we can just +load it from python? + +Can we drop the decl-list.txt file (or rename to make sure this is what a +generated section.txt would look like) + + += Issues = +* gtkdoc-fixxref makefile targets use $HTML_DIR + * HTML_DIR: The directory where gtk-doc generated documentation is installed + it comes from gtk-doc.m4 (--with-html-dir) but has no default + * automake exports $htmldir which is by default: + ${prefix}/share/doc/${PACKAGE_TARNAME} + * the Makefile uses $(DESTDIR)$(TARGET_DIR) + where TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE) + http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html +* gtkdoc does not know about module versions + * this is causing troubles when multiple library versions are installed + (gtk+-{2,3}, gstreamer-{0.8,0.10,1.0} + * right now gtk-doc is xreffing against any <module>/*.devhelp2 found + * just using the one with a higher number won't work + + += Extensibility = +We'd like to extend gtk-doc to understand conventions/features of gobject libs. +Ideally libs register their extension hooks, so that other libs that use these +libs can benefit from the extensions too. + +== custom get_types collector == +- the default method takes the types from a type file +- gstreamer plugin docs take a list of types from the gst plugin registry + +== custom properties == +- gtk has style and child properties + +== extra gobject property flags == +- gstreamer has 'controllable' properties + += Output = +* http://sagehill.net/docbookxsl/index.html +* multipage-html + * would be good to be able to have page titles as a concatenation of document + name and page name (gtk+:GtkWIdget) +* formats + http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf + http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man + we need more configure options in gtk-doc.m4: + --(enable|disable)-gtk-doc-(html|pdf|man) + - html : enabled by default +* validation + xmllint --noout --xinclude --postvalid tester-docs.xml + xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd + - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip + += Warnings = +Bugzilla has some requests for extra warnings. We should support a common +commandline option(s) in all tools to enable/disable the warnings. The makefiles +should pass the flags from an env-var (GTKDOC_OPTIONS). The env-var should be +used after the regular flags, so that the env-var can override hardcoded +settings (in Makefile.am). + +Lets take this warning for the example: + "Symbol name not found at the start of the comment block." + +Version 1: (template "warn-xxx!, warn-yyy!") +--warn-missing-symbol-at-comment-start +--no-warn-missing-symbol-at-comment-start + +Version 2: (template "warn:s@") +-Wmissing-symbol-at-comment-start +-Wno-missing-symbol-at-comment-start +-warn missing-symbol-at-comment-start +-warn no-missing-symbol-at-comment-start + +more warnings: + - 'deprecated' deprecating 'features' + - 'dummy-docs' check if symbol docs are very short and repeat mainly words + from the symbol. + - possible xrefs (e.g. adding a # or () would make it a successful xref) + + += GIR = +== scanning == +* ideas + * use gir files + 1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files or + patch gtkdoc-scan/gtkdoc-scangobject to output gir files + 2) patch gtkdoc-mkdb to read stuff from gir instead of classical files + * if gir-files would have the comments too (they are getting this now): + * we could even drop scanning the sources + * IDEs could use the gir-files to show doc-tooltips for symbols + * we might need yet another makefile flavour to use gir files +* perl and xml + * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html + +== binding docs == +* simmillar workflow to gettext +* add gtkdoc-mk??? to generate binding doc templates + * have c-comments there as comments + * when updating templates, mark sections that have changed as fuzzy +* add options to gtkdoc-mkdb to build docbook from those templates +* questions + * could we use the tmpl file mechanism? + * directory structure? + * we need to list the languages like ALL_LINGUAS for translations + * we need to create subdirs for binding docs, ideally we use one for 'C' as well +* devhelp + * devhelp files need a language attribute in the book-tag + language={C,C++,JavaScript,Perl,Python,...} + * devhelp could show a selector for the language + * need to get existing python/~mm docs to use it, gtk-doc could output + language=C for own docs + +=== installation === +* need to install each book with a prefix +* would be good to have a language attribute in book tag to allow filter by language +* look at /usr/share/gtk-doc/html/pygobject/index.html + + += external processors = +We need parametric, user definable macros. +|[ ... ]| - programlistings +|macro(arg1,arg2,...)[ ... ]| - call macro + - pass args as parameters (on the commandline) + - pass some gtk-doc vars in environment + (gtk-doc version, module, srcdir, buildir) + - content of [] on stdin or as a file + - get output on stdout or file + - and replace the macro with it +The changes could be made in gtkdoc-mkdb::ExpandAbbreviations() +== example macros == +|highlight(c)[...]| - highlight source code for a specific language (c) + - what will this output? preformatted html to be xincluded? + - we could have macros for each format, the docbook xml macro would leave + enough traces in the html so that a html macro can continue +|dot(svg)[...]| - format dot graph and include result as mediaobject (in svg format) +|ditta(svg)[...]| - parse ascii art and include result as mediaobject (in svg format) + - we need to generate a filename for the image or use anoter parameter + +== where to define macros == +* system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir) +* prefix for custom macros? +* we could require stdin for input and stdout for output, the wrapper for the + actual tool can ensure the convention + + += styling = +=== process html === +if we highlight to html we get colors, we need to check what tags we should process though: +<pre class="programlisting"> is used for all code boxes. +<div class="informalexample"><pre class="programlisting"> is used for examples. +problems: +* in html we don't know the language anymore + * add another div +* with source-highlight, constants and types are not markedup. + for types we might need to build an own lang file dynamically and include + /usr/share/source-highlight/c.lang +=== |[ ... ]| does not allow setting the language === +* check for vi/emacs/jedit modelines + jedit: http://www.jedit.org/users-guide/buffer-local.html + vim: http://vim.wikia.com/wiki/Modeline_magic + emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html +* allow <!-- language="C" --> comments after |[ +* we need to catch those when processing the docbook and expanding the |[ +* require new macro syntax + +== show inherited api == +could we write small html files for each object for methods, signals and properties and then use iframes to combine those at runtime like in javadoc? +could we do that using javascript and some other magic? + + += Markup = +== tags == +* to document the api-life cycle we have: since, deprecated and stability: +* other things we might want to specify: + * multi-threading safety: mt-safe, use-with-lock <lock> + +== protected scope == +* we can have /* < protected > */ in classes +* we can have <SUBSECTION Protected> in -section.txt +* ideally we have Scope: {Public, Protected, Private} supported in doc comments +* there is a bug for gir, https://bugzilla.gnome.org/show_bug.cgi?id=594125 + +== wildcards in symbol names == +Sometimes one defines a set of function and macros with very similar purpose, e.g. +READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol +READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have +all matching declarations in one source listing. Multiple wildcards are okay. + + += documentation best practises #518427 = +* we'd like offer a more complete skelleton + * structure + * docbook markup (part/chapter structure) +* structure + Suggested structure for api-docs. + Idea is to have more content that api reference. It would be good to have a + gnome-platform document in devhelp, so that we could xref that instead of + explaining 100 times how to use pkg-config. + + * examples + * gobject in devhelp + * concepts / api / tools / tutorial / related tools + * gtk in devhelp + * overview / api / migation / tools + * qt reference docs in qt assistant + * classes / overview / tutorial&examples + * recommendation + * front-page + * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html) + (problem: what enclosing tag) + Logo, Module Version + Copyright and Legalnotice + Links + * homepage, mailing lists, irc channel + * repository, source releases, bugtracker + * TOC + * introduction - what is is about + * concepts - explain basic ideas and terminology + * development - how to build and run, env-vars, different platforms + * api - classic api docs + * tutorial & examples - integrated to keep it up-to-date and cross referenced + * migration - how to for api changes, deprecations + * (related) tools - tools part of the package or recommended for development + * indexes - api-index, depretations, new api since xxx + +proposed structure in docbook xml: +<book> + <bookinfo> + </bookinfo> + <preface><title>Introduction + ... + + xxx Overview + + ... + + xxx Core Reference + + ... + + xxx Object Reference + Object Hierarchy + + + ... + + ... + + +some things to check: +* gtk,glib: can we make a for the glosary and index's (according to docbook, yes) + should we use ? its like a chapter. +* gobject: uses a for introductions +* gobject: uses as a parent for the xi:includeed docs + + += extra link for symbols = +need options for configure: +--enable-gtk-doc-codesearch-links +--enable-gtk-doc-liveedit-links +== viewvc,cgit,... == +- link to some online service for the code +- problem: most don't have local anchors for the symbols +- where to set the uri (in the document, like for online url)? +- what about a template URL containing a %s for the "path/file" or a special macro + http://svn.gnome.org/viewvc/gtk-doc/trunk/tests/gobject/src/gobject.c?view=markup + http://buzztard.svn.sourceforge.net/viewvc/buzztard/trunk/buzztard/src/lib/core/core.c?view=markup + - unfortunately we can't link to symbols (only lines) + - linking to files is difficult as in gtkdoc we have modules + +== codesearch == +- google (code) link : http://www.google.com/codesearch?q=g_object_unref +== live editing == +The idea is to have an 'edit' link in an online version of the docs (build from +head development version) per doc-entry (symbols and section). +The link goes to a cgi and that gets following parameters: docmodule,symbol. +E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new +The cgi would need a hashmap to get from docmodule to the way to check it out +(ideally it has a recent checkout and only updates it). +problems: +- signal that this has been edited already? +- support for xi:included examples +- updating the checkout could be slow + + += fix missing since docs = +cd gstreamer/gstreamer/docs/gst +gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince +cd gstreamer/gstreamer/src +git bisect start +git bisect good +git bisect bad RELEASE-0_10_0 +git bisect run script.sh + +script: +#!/bin/sh +make ctags +grep "gst_caps_is_always_compatible" tags + + += performance = +- timestamp each step + make check >make.log +- try CFLAGS=-O0 for compiling the scanner, no need to optimize it + CFLAGS="-O0" make check >make.log + safes max 0.5 sec. +- xslt + http://docbook2x.sourceforge.net/latest/doc/performance.html + - play with xsltproc --profile --verbose --timing + cd tests/gobject/docs/html + time /usr/bin/xsltproc 2>xslt.log --profile --verbose --timing --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml + - l10n.language is slow + bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750 + see: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg05412.html + - override l10n.language + glib/gobject + real user sys + 2m15.221s 1m58.740s 0m1.456s + > + 1m55.480s 1m44.296s 0m2.125s + - override many template related to gentext + real user sys + 0m43.327s 0m38.594s 0m4.724s + > + real user sys + 0m33.282s 0m29.266s 0m4.012s + - removing the gentext calls for nav-bar alt tags does not help + + - we could do the xinlcude processing once and use it for both html and pdf + time /usr/bin/xsltproc 2>../xslt4.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml + real user sys + 0m4.846s 0m4.434s 0m0.147s + 0m4.842s 0m4.386s 0m0.145s + + + time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml + real user sys + 0m0.596s 0m0.546s 0m0.023s + + time /usr/bin/xsltproc 2>../xslt5.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ./tester-docs-all.xml + real user sys + 0m4.167s 0m3.834s 0m0.106s + 0m4.248s 0m3.851s 0m0.114s + + + time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml + + real user sys + 0m0.700s 0m0.636s 0m0.034s + + time /usr/bin/xsltproc 2>../xslt6.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ./tester-docs-all2.xml + + real user sys + 0m3.344s 0m3.026s 0m0.109s + 0m3.372s 0m3.037s 0m0.115s + + + l ../tester-docs.xml ./tester-docs-all*.xml + + - we could also try to compact the installed xslt + xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '//! { N; b c; }; /-->/s///g }; /^ *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl + - unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could + - strip comments + - process xsl:import and xsl:include + - extra xsltproc options: + --novalid: saves ~ 0.12 sec + + - strip DOCTYPES on xincludes + - there is a performance bottleneck in libxml, where it parses DTD for each fragment + - we're using the dtd to + - validate fragments + - inject package name/version etc. + - 1) we could provide a flags to gtkdoc-mkdb to not put any doctype on + generated file and manually result entities in generated files (and + expand_content_files) + - to get a list of entities: + - we could parse entities from the main doc-file header + - tricky as with xml/gtkdocentities.ent, they are in a extra file + - we could pass entities as args for gtkdoc-mkdb + - if the flag is used, we should warn if entities are in the header + - 2) if the doctype on the main doc, does not cotnain entities, skip adding + the doctype to generated output + - 3) if the doctype on the main doc contains entities, only add the doctype + if the generated content contains entities ([&%][_a-zA-Z]*;) + - a quick check on the gnome modules showed: + - quite a few don't use entities + - those that use version.xml + - seem to mostly use it in the main doc + - but a few use it for man pages + find . -name "*.xml" -exec grep -Hn "&version;" {} \; | grep -v "\-docs.xml" + +find . -name "*.xml" -exec egrep --color -Hn '&[_a-zA-Z]*;' {} \; | egrep -v '&(amp|lt|gt|quot|apos|nbsp);' | egrep --color '&[_a-zA-Z]*;' +find . -name "*.xml" -exec egrep -o '&[_a-zA-Z]*;' {} \; | sort | uniq -c | sort -n + += python = +- consider swithcing to this markdown parser + https://pythonhosted.org/Markdown/index.html +- switch intermediate files to json/yaml + - we need to pick something, that we can easily output from plain c (produced by gtkdoc-scangobj) + - decl-list.txt and .types would need to stay + - maybe maintain one file per sourcefile (in a subdir) to eventually be able to + do incremental builds +- refactor Read{Args,Declarations,Signals}File to output into a single dictionary each: + Signal{Names,Objects,Returns,...}[key] -> Signals[key].{names,objects,returns,...} diff --git a/gtk-doc-for-gtk4/autogen.sh b/gtk-doc-for-gtk4/autogen.sh new file mode 100755 index 0000000000..27d402558c --- /dev/null +++ b/gtk-doc-for-gtk4/autogen.sh @@ -0,0 +1,19 @@ +#!/bin/sh +# Run this to generate all the initial makefiles, etc. + +test -n "$srcdir" || srcdir=`dirname "$0"` +test -n "$srcdir" || srcdir=. + +olddir=`pwd` +cd "$srcdir" + +AUTORECONF=`which autoreconf` +if test -z $AUTORECONF; then + echo "*** No autoreconf found, please install it ***" + exit 1 +else + autoreconf --force --install --verbose || exit $? +fi + +cd "$olddir" +test -n "$NOCONFIGURE" || "$srcdir/configure" "$@" diff --git a/gtk-doc-for-gtk4/bugzilla.py b/gtk-doc-for-gtk4/bugzilla.py new file mode 100755 index 0000000000..583a628e41 --- /dev/null +++ b/gtk-doc-for-gtk4/bugzilla.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python +# -*- Mode: Python -*- +# vi:si:et:sw=4:sts=4:ts=4 + + +# parse HTML from bugzilla.gnome.org to create a list of bugs for a given +# product, component and target_milestone + +import re +import os +import sys +import codecs +import urllib +import HTMLParser + +# a sample bug line we parse for future reference: +# + +# a sample bug section after olav's updating of bugzilla +# +# +# +# +# +# +# +# +# +# +# + + +URL = 'http://bugzilla.gnome.org/buglist.cgi?product=%s&component=%s&target_milestone=%s' + +# reg = re.compile('(.*)<\/td') + +HEADER = ' Changes\n' +ITEM = ' o %s : %s' +FOOTER = '\n Contributors\n' + +default_product = "gtk-doc" + +TD_ID = 1 +TD_SUMMARY = 7 +# after Olav's changes, it's now number 8 +#TD_SUMMARY = 8 + +# Horrible, don't look here +class HP(HTMLParser.HTMLParser): + def __init__(self): + HTMLParser.HTMLParser.__init__(self) + self.tr = 0 + self.td = 0 + self.bugs = [] + self.bugno = 0 + self.descr = "" + + def handle_starttag(self, tag, data): + if tag == 'tr': + self.tr = 1 + return + # count td's + elif self.tr and tag.startswith('td'): + self.td += 1 + + # all > refs are handled through this method; append them to self.descr + def handle_entityref(self, name): + self.descr += " &%s; " % name + + # can be called more than once for one td + def handle_data(self, data): + if not self.tr: + return + data = data.strip() + if not data: + return + + #print self.td, self.tr, repr(data) + + # check what td it is in + if self.td == TD_ID: + try: + self.bugno = int(data) + #print "got id: ", self.bugno + except ValueError: + self.bugno = 0 + elif self.td == TD_SUMMARY: + # the summary td + self.descr += data + #print "got descr: ", self.descr + + def handle_endtag(self, tag): + if tag == 'tr': + self.tr = 0 + self.td = 0 + #print "end tag: ", self.bugno, self.descr + if self.bugno != 0: + self.bugs.append((self.bugno, self.descr)) + self.bugno = 0 + self.descr = "" + +def main(args): + if len(args) < 3: + print 'Usage: %s component milestone [product] [file]' % args[0] + return 2 + + component = args[1] + milestone = args[2] + + if len(args) <= 3: + product = default_product + else: + product = args[3] + + if len(args) <= 4: + output = None + else: + output = args[4] + + url = URL % (product, urllib.quote(component), milestone) + fd = urllib.urlopen(url) + + hp = HP() + hp.feed(fd.read()) + + lines = ["\n", ] + lines.append(HEADER) + for bug_id, summary in hp.bugs: + lines.append(ITEM % (bug_id, summary)) + lines.append(FOOTER) + bugs = "\n".join(lines) + + if not output: + print bugs + else: + # get original + #doc = codecs.open(output, "r", encoding='utf-8').read() + doc = open(output, "r").read() + matcher = re.compile('(.*).*(.*)', + re.DOTALL) + match = matcher.search(doc) + pre = match.expand('\\1') + post = match.expand('\\2') + + backup = output + ".bugs.bak" + os.rename(output, backup) + handle = open(output, "w") + handle.write(pre + bugs + post) + +if __name__ == '__main__': + sys.exit(main(sys.argv)) diff --git a/gtk-doc-for-gtk4/buildsystems/autotools/Makefile.am b/gtk-doc-for-gtk4/buildsystems/autotools/Makefile.am new file mode 100644 index 0000000000..dde0d11eac --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/autotools/Makefile.am @@ -0,0 +1,25 @@ +EXTRA_DIST = \ + $(autotoolsdata_DATA) \ + gtk-doc.m4 + +CLEANFILES = gtk-doc.flat.make gtk-doc.no-xslt-flat.make + +bin_SCRIPTS = gtkdocize + +autotoolsdatadir = $(datadir)/gtk-doc/data +autotoolsdata_DATA = \ + gtk-doc.make \ + gtk-doc.flat.make \ + gtk-doc.no-xslt.make \ + gtk-doc.no-xslt-flat.make + +aclocaldir = $(datadir)/aclocal +aclocal_DATA = gtk-doc.m4 + +gtk-doc.flat.make: gtk-doc.make + @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ + +gtk-doc.no-xslt-flat.make: gtk-doc.no-xslt.make + @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ + +-include $(top_srcdir)/git.mk diff --git a/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.m4 b/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.m4 new file mode 100644 index 0000000000..2d12f01f4b --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.m4 @@ -0,0 +1,113 @@ +# -*- mode: autoconf -*- +# +# gtk-doc.m4 - configure macro to check for gtk-doc +# Copyright (C) 2003 James Henstridge +# 2007-2017 Stefan Sauer +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +# +# As a special exception, the above copyright owner gives unlimited +# permission to copy, distribute and modify the configure scripts that +# are the output of Autoconf when processing the Macro. You need not +# follow the terms of the GNU General Public License when using or +# distributing such scripts, even though portions of the text of the +# Macro appear in them. The GNU General Public License (GPL) does govern +# all other use of the material that constitutes the Autoconf Macro. + +# serial 2 + +dnl Usage: +dnl GTK_DOC_CHECK([minimum-gtk-doc-version]) +AC_DEFUN([GTK_DOC_CHECK], +[ + AC_REQUIRE([PKG_PROG_PKG_CONFIG]) + AC_BEFORE([AC_PROG_LIBTOOL],[$0])dnl setup libtool first + AC_BEFORE([AM_PROG_LIBTOOL],[$0])dnl setup libtool first + + ifelse([$1],[],[gtk_doc_requires="gtk-doc"],[gtk_doc_requires="gtk-doc >= $1"]) + AC_MSG_CHECKING([for gtk-doc]) + PKG_CHECK_EXISTS([$gtk_doc_requires],[have_gtk_doc=yes],[have_gtk_doc=no]) + AC_MSG_RESULT($have_gtk_doc) + + if test "$have_gtk_doc" = "no"; then + AC_MSG_WARN([ + You will not be able to create source packages with 'make dist' + because $gtk_doc_requires is not found.]) + fi + + dnl check for tools we added during development + dnl Use AC_CHECK_PROG to avoid the check target using an absolute path that + dnl may not be writable by the user. Currently, automake requires that the + dnl test name must end in '.test'. + dnl https://bugzilla.gnome.org/show_bug.cgi?id=701638 + AC_CHECK_PROG([GTKDOC_CHECK],[gtkdoc-check],[gtkdoc-check.test]) + AC_PATH_PROG([GTKDOC_CHECK_PATH],[gtkdoc-check]) + AC_PATH_PROGS([GTKDOC_REBASE],[gtkdoc-rebase],[true]) + AC_PATH_PROG([GTKDOC_MKPDF],[gtkdoc-mkpdf]) + + dnl for overriding the documentation installation directory + AC_ARG_WITH([html-dir], + AS_HELP_STRING([--with-html-dir=PATH], [path to installed docs]),, + [with_html_dir='${datadir}/gtk-doc/html']) + HTML_DIR="$with_html_dir" + AC_SUBST([HTML_DIR]) + + dnl enable/disable documentation building + AC_ARG_ENABLE([gtk-doc], + AS_HELP_STRING([--enable-gtk-doc], + [use gtk-doc to build documentation [[default=no]]]),, + [enable_gtk_doc=no]) + + AC_MSG_CHECKING([whether to build gtk-doc documentation]) + AC_MSG_RESULT($enable_gtk_doc) + + if test "x$enable_gtk_doc" = "xyes" && test "$have_gtk_doc" = "no"; then + AC_MSG_ERROR([ + You must have $gtk_doc_requires installed to build documentation for + $PACKAGE_NAME. Please install gtk-doc or disable building the + documentation by adding '--disable-gtk-doc' to '[$]0'.]) + fi + + dnl don't check for glib if we build glib + if test "x$PACKAGE_NAME" != "xglib"; then + dnl don't fail if someone does not have glib + PKG_CHECK_MODULES(GTKDOC_DEPS, glib-2.0 >= 2.10.0 gobject-2.0 >= 2.10.0,,[:]) + fi + + dnl enable/disable output formats + AC_ARG_ENABLE([gtk-doc-html], + AS_HELP_STRING([--enable-gtk-doc-html], + [build documentation in html format [[default=yes]]]),, + [enable_gtk_doc_html=yes]) + AC_ARG_ENABLE([gtk-doc-pdf], + AS_HELP_STRING([--enable-gtk-doc-pdf], + [build documentation in pdf format [[default=no]]]),, + [enable_gtk_doc_pdf=no]) + + if test -z "$GTKDOC_MKPDF"; then + enable_gtk_doc_pdf=no + fi + + if test -z "$AM_DEFAULT_VERBOSITY"; then + AM_DEFAULT_VERBOSITY=1 + fi + AC_SUBST([AM_DEFAULT_VERBOSITY]) + + AM_CONDITIONAL([HAVE_GTK_DOC], [test x$have_gtk_doc = xyes]) + AM_CONDITIONAL([ENABLE_GTK_DOC], [test x$enable_gtk_doc = xyes]) + AM_CONDITIONAL([GTK_DOC_BUILD_HTML], [test x$enable_gtk_doc_html = xyes]) + AM_CONDITIONAL([GTK_DOC_BUILD_PDF], [test x$enable_gtk_doc_pdf = xyes]) + AM_CONDITIONAL([GTK_DOC_USE_LIBTOOL], [test -n "$LIBTOOL"]) + AM_CONDITIONAL([GTK_DOC_USE_REBASE], [test -n "$GTKDOC_REBASE"]) +]) diff --git a/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.make b/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.make new file mode 100644 index 0000000000..7d9a27f34b --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.make @@ -0,0 +1,321 @@ +# -*- mode: makefile -*- +# +# gtk-doc.make - make rules for gtk-doc +# Copyright (C) 2003 James Henstridge +# 2004-2007 Damon Chaplin +# 2007-2017 Stefan Sauer +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +#################################### +# Everything below here is generic # +#################################### + +if GTK_DOC_USE_LIBTOOL +GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +GTKDOC_RUN = $(LIBTOOL) --mode=execute +else +GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +GTKDOC_RUN = +endif + +# We set GPATH here; this gives us semantics for GNU make +# which are more like other make's VPATH, when it comes to +# whether a source that is a target of one rule is then +# searched for in VPATH/GPATH. +# +GPATH = $(srcdir) + +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +SETUP_FILES = \ + $(content_files) \ + $(expand_content_files) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt + +EXTRA_DIST = \ + $(HTML_IMAGES) \ + $(SETUP_FILES) + +DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \ + html-build.stamp pdf-build.stamp \ + sgml.stamp html.stamp pdf.stamp + +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals + +REPORT_FILES = \ + $(DOC_MODULE)-undocumented.txt \ + $(DOC_MODULE)-undeclared.txt \ + $(DOC_MODULE)-unused.txt + +gtkdoc-check.test: Makefile + $(AM_V_GEN)echo "#!/bin/sh -e" > $@; \ + echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \ + chmod +x $@ + +CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test + +if GTK_DOC_BUILD_HTML +HTML_BUILD_STAMP=html-build.stamp +else +HTML_BUILD_STAMP= +endif +if GTK_DOC_BUILD_PDF +PDF_BUILD_STAMP=pdf-build.stamp +else +PDF_BUILD_STAMP= +endif + +all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) +.PHONY: all-gtk-doc + +if ENABLE_GTK_DOC +all-local: all-gtk-doc +endif + +docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) + +$(REPORT_FILES): sgml-build.stamp + +#### setup #### + +GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_@AM_V@) +GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_@AM_DEFAULT_V@) +GTK_DOC_V_SETUP_0=@echo " DOC Preparing build"; + +setup-build.stamp: + -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ + files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + destdir=`dirname $(abs_builddir)/$$file`; \ + test -d "$$destdir" || mkdir -p "$$destdir"; \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ + done; \ + fi; \ + fi + $(AM_V_at)touch setup-build.stamp + +#### scan #### + +GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_@AM_V@) +GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_@AM_DEFAULT_V@) +GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files"; + +GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_@AM_V@) +GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_@AM_DEFAULT_V@) +GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects"; + +scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) + $(GTK_DOC_V_SCAN)_source_dir='' ; \ + for i in $(DOC_SOURCE_DIR) ; do \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ + done ; \ + gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) + $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ + scanobj_options=""; \ + gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$$?" = "0"; then \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + fi; \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ + else \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi + $(AM_V_at)touch scan-build.stamp + +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp + @true + +#### xml #### + +GTK_DOC_V_XML=$(GTK_DOC_V_XML_@AM_V@) +GTK_DOC_V_XML_=$(GTK_DOC_V_XML_@AM_DEFAULT_V@) +GTK_DOC_V_XML_0=@echo " DOC Building XML"; + +sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent + $(GTK_DOC_V_XML)_source_dir='' ; \ + for i in $(DOC_SOURCE_DIR) ; do \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ + done ; \ + gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) + $(AM_V_at)touch sgml-build.stamp + +sgml.stamp: sgml-build.stamp + @true + +$(DOC_MAIN_SGML_FILE): sgml-build.stamp + @true + +xml/gtkdocentities.ent: Makefile + $(GTK_DOC_V_XML)$(MKDIR_P) $(@D) && ( \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + ) > $@ + +#### html #### + +GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_@AM_V@) +GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@) +GTK_DOC_V_HTML_0=@echo " DOC Building HTML"; + +GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_@AM_V@) +GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_@AM_DEFAULT_V@) +GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references"; + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) + $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \ + mkhtml_options=""; \ + gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$$?" = "0"; then \ + if test "x$(V)" = "x1"; then \ + mkhtml_options="$$mkhtml_options --verbose"; \ + fi; \ + fi; \ + gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \ + if test "$$?" = "0"; then \ + mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \ + fi; \ + cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + -@test "x$(HTML_IMAGES)" = "x" || \ + for file in $(HTML_IMAGES) ; do \ + test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ + test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \ + test -f $$file && cp $$file $(abs_builddir)/html; \ + done; + $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + $(AM_V_at)touch html-build.stamp + +#### pdf #### + +GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_@AM_V@) +GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_@AM_DEFAULT_V@) +GTK_DOC_V_PDF_0=@echo " DOC Building PDF"; + +pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) + $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \ + mkpdf_options=""; \ + gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$$?" = "0"; then \ + if test "x$(V)" = "x1"; then \ + mkpdf_options="$$mkpdf_options --verbose"; \ + fi; \ + fi; \ + if test "x$(HTML_IMAGES)" != "x"; then \ + for img in $(HTML_IMAGES); do \ + part=`dirname $$img`; \ + echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \ + if test $$? != 0; then \ + mkpdf_options="$$mkpdf_options --imgdir=$$part"; \ + fi; \ + done; \ + fi; \ + gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) + $(AM_V_at)touch pdf-build.stamp + +############## + +clean-local: + @rm -f *~ *.bak + @rm -rf .libs + @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \ + rm -f $(DOC_MODULE).types; \ + fi + @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \ + rm -f $(DOC_MODULE)-sections.txt; \ + fi + +distclean-local: + @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \ + $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ + rm -f $(SETUP_FILES) $(DOC_MODULE).types; \ + fi + +maintainer-clean-local: + @rm -rf xml html + +install-data-local: + @installfiles=`echo $(builddir)/html/*`; \ + if test "$$installfiles" = '$(builddir)/html/*'; \ + then echo 1>&2 'Nothing to install' ; \ + else \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + $(mkinstalldirs) $${installdir} ; \ + for i in $$installfiles; do \ + echo ' $(INSTALL_DATA) '$$i ; \ + $(INSTALL_DATA) $$i $${installdir}; \ + done; \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + mv -f $${installdir}/$(DOC_MODULE).devhelp2 \ + $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \ + fi; \ + $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \ + fi + +uninstall-local: + @if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + rm -rf $${installdir} + +# +# Require gtk-doc when making dist +# +if HAVE_GTK_DOC +dist-check-gtkdoc: docs +else +dist-check-gtkdoc: + @echo "*** gtk-doc is needed to run 'make dist'. ***" + @echo "*** gtk-doc was not found when 'configure' ran. ***" + @echo "*** please install gtk-doc and rerun 'configure'. ***" + @false +endif + +dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local + @mkdir $(distdir)/html + @cp ./html/* $(distdir)/html + @-cp ./$(DOC_MODULE).pdf $(distdir)/ + @-cp ./$(DOC_MODULE).types $(distdir)/ + @-cp ./$(DOC_MODULE)-sections.txt $(distdir)/ + @cd $(distdir) && rm -f $(DISTCLEANFILES) + @$(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html + +.PHONY : dist-hook-local docs diff --git a/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.no-xslt.make b/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.no-xslt.make new file mode 100644 index 0000000000..26a98bdf0e --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/autotools/gtk-doc.no-xslt.make @@ -0,0 +1,309 @@ +# -*- mode: makefile -*- +# +# gtk-doc.make - make rules for gtk-doc +# Copyright (C) 2003 James Henstridge +# 2004-2007 Damon Chaplin +# 2007-2017 Stefan Sauer +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +#################################### +# Everything below here is generic # +#################################### + +if GTK_DOC_USE_LIBTOOL +GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +GTKDOC_RUN = $(LIBTOOL) --mode=execute +else +GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +GTKDOC_RUN = +endif + +# We set GPATH here; this gives us semantics for GNU make +# which are more like other make's VPATH, when it comes to +# whether a source that is a target of one rule is then +# searched for in VPATH/GPATH. +# +GPATH = $(srcdir) + +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +SETUP_FILES = \ + $(content_files) \ + $(expand_content_files) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt + +EXTRA_DIST = \ + $(HTML_IMAGES) \ + $(SETUP_FILES) + +DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \ + html-build.stamp pdf-build.stamp \ + sgml.stamp html.stamp pdf.stamp + +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals + +REPORT_FILES = \ + $(DOC_MODULE)-undocumented.txt \ + $(DOC_MODULE)-undeclared.txt \ + $(DOC_MODULE)-unused.txt + +gtkdoc-check.test: Makefile + $(AM_V_GEN)echo "#!/bin/sh -e" > $@; \ + echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \ + chmod +x $@ + +CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test + +if GTK_DOC_BUILD_HTML +HTML_BUILD_STAMP=html-build.stamp +else +HTML_BUILD_STAMP= +endif +if GTK_DOC_BUILD_PDF +PDF_BUILD_STAMP=pdf-build.stamp +else +PDF_BUILD_STAMP= +endif + +all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) +.PHONY: all-gtk-doc + +if ENABLE_GTK_DOC +all-local: all-gtk-doc +endif + +docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) + +$(REPORT_FILES): sgml-build.stamp + +#### setup #### + +GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_@AM_V@) +GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_@AM_DEFAULT_V@) +GTK_DOC_V_SETUP_0=@echo " DOC Preparing build"; + +setup-build.stamp: + -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ + files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + destdir=`dirname $(abs_builddir)/$$file`; \ + test -d "$$destdir" || mkdir -p "$$destdir"; \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ + done; \ + fi; \ + fi + $(AM_V_at)touch setup-build.stamp + +#### scan #### + +GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_@AM_V@) +GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_@AM_DEFAULT_V@) +GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files"; + +GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_@AM_V@) +GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_@AM_DEFAULT_V@) +GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects"; + +scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) + $(GTK_DOC_V_SCAN)_source_dir='' ; \ + for i in $(DOC_SOURCE_DIR) ; do \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ + done ; \ + gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) + $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ + scanobj_options=""; \ + gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$$?" = "0"; then \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + fi; \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ + else \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi + $(AM_V_at)touch scan-build.stamp + +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp + @true + +#### xml #### + +GTK_DOC_V_XML=$(GTK_DOC_V_XML_@AM_V@) +GTK_DOC_V_XML_=$(GTK_DOC_V_XML_@AM_DEFAULT_V@) +GTK_DOC_V_XML_0=@echo " DOC Building XML"; + +sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent + $(GTK_DOC_V_XML)_source_dir='' ; \ + for i in $(DOC_SOURCE_DIR) ; do \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ + done ; \ + gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) + $(AM_V_at)touch sgml-build.stamp + +sgml.stamp: sgml-build.stamp + @true + +$(DOC_MAIN_SGML_FILE): sgml-build.stamp + @true + +xml/gtkdocentities.ent: Makefile + $(GTK_DOC_V_XML)$(MKDIR_P) $(@D) && ( \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + echo ""; \ + ) > $@ + +#### html #### + +GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_@AM_V@) +GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@) +GTK_DOC_V_HTML_0=@echo " DOC Building HTML"; + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) + $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \ + mkhtml_options="--path=\"$(abs_srcdir)\""; \ + if test "x$(V)" = "x1"; then \ + mkhtml_options="$$mkhtml_options --verbose"; \ + fi; \ + cd html && gtkdoc-mkhtml2 $$mkhtml_options $(MKHTML_OPTIONS) $(FIXXREF_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + -@test "x$(HTML_IMAGES)" = "x" || \ + for file in $(HTML_IMAGES) ; do \ + test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ + test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \ + test -f $$file && cp $$file $(abs_builddir)/html; \ + done; + $(AM_V_at)touch html-build.stamp + +#### pdf #### + +GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_@AM_V@) +GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_@AM_DEFAULT_V@) +GTK_DOC_V_PDF_0=@echo " DOC Building PDF"; + +pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) + $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \ + mkpdf_options=""; \ + gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$$?" = "0"; then \ + if test "x$(V)" = "x1"; then \ + mkpdf_options="$$mkpdf_options --verbose"; \ + fi; \ + fi; \ + if test "x$(HTML_IMAGES)" != "x"; then \ + for img in $(HTML_IMAGES); do \ + part=`dirname $$img`; \ + echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \ + if test $$? != 0; then \ + mkpdf_options="$$mkpdf_options --imgdir=$$part"; \ + fi; \ + done; \ + fi; \ + gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) + $(AM_V_at)touch pdf-build.stamp + +############## + +clean-local: + @rm -f *~ *.bak + @rm -rf .libs + @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \ + rm -f $(DOC_MODULE).types; \ + fi + @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \ + rm -f $(DOC_MODULE)-sections.txt; \ + fi + +distclean-local: + @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \ + $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ + rm -f $(SETUP_FILES) $(DOC_MODULE).types; \ + fi + +maintainer-clean-local: + @rm -rf xml html + +install-data-local: + @installfiles=`echo $(builddir)/html/*`; \ + if test "$$installfiles" = '$(builddir)/html/*'; \ + then echo 1>&2 'Nothing to install' ; \ + else \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + $(mkinstalldirs) $${installdir} ; \ + for i in $$installfiles; do \ + echo ' $(INSTALL_DATA) '$$i ; \ + $(INSTALL_DATA) $$i $${installdir}; \ + done; \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + mv -f $${installdir}/$(DOC_MODULE).devhelp2 \ + $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \ + fi; \ + $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \ + fi + +uninstall-local: + @if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + rm -rf $${installdir} + +# +# Require gtk-doc when making dist +# +if HAVE_GTK_DOC +dist-check-gtkdoc: docs +else +dist-check-gtkdoc: + @echo "*** gtk-doc is needed to run 'make dist'. ***" + @echo "*** gtk-doc was not found when 'configure' ran. ***" + @echo "*** please install gtk-doc and rerun 'configure'. ***" + @false +endif + +dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local + @mkdir $(distdir)/html + @cp ./html/* $(distdir)/html + @-cp ./$(DOC_MODULE).pdf $(distdir)/ + @-cp ./$(DOC_MODULE).types $(distdir)/ + @-cp ./$(DOC_MODULE)-sections.txt $(distdir)/ + @cd $(distdir) && rm -f $(DISTCLEANFILES) + @$(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html + +.PHONY : dist-hook-local docs diff --git a/gtk-doc-for-gtk4/buildsystems/autotools/gtkdocize.in b/gtk-doc-for-gtk4/buildsystems/autotools/gtkdocize.in new file mode 100755 index 0000000000..83127bfa17 --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/autotools/gtkdocize.in @@ -0,0 +1,170 @@ +#!/bin/sh + +progname=`echo "$0" | sed 's%^.*/%%'` + +PROGRAM=gtkdocize +PACKAGE=@PACKAGE@ +VERSION=@VERSION@ + +prefix=@prefix@ +datarootdir=@datarootdir@ +datadir=@datadir@ + +# options +copy=no +makefile=gtk-doc.make +flavour=no-tmpl + +# mini help +usage="\ +usage: $progname [ --copy ] [ --docdir DIR ] [ --flavour {legacy|legacy-flat|no-tmpl|no-tmpl-flat|no-xslt|no-xslt-flat} ] [ --srcdir DIR ]" + +# Find the srcdir early (and ignore a srcdir set in configure). +# https://bugzilla.gnome.org/show_bug.cgi?id=707426 +args="$*" +while test $# -gt 0; do + case "$1" in + --srcdir) + shift + srcdir="$1" + shift ;; + --srcdir=*) + srcdir=`expr "X$1" : '[^=]*=\(.*\)'` + shift ;; + *) + shift ;; + esac +done +set - $args + +# assume working directory if srcdir is not set +test "$srcdir" || srcdir=. +test "$docdir" || docdir="$srcdir" + +# detect configure script +no_configure_found=0 +if test -f "$srcdir"/configure.ac; then + configure="$srcdir"/configure.ac +elif test -f "$srcdir"/configure.in; then + configure="$srcdir"/configure.in +else + no_configure_found=1 +fi + +# check configure script for GTK_DOC_CHECK macro +no_gtk_doc_check_found=0 +if test $no_configure_found -eq 0; then + macro=`grep '^GTK_DOC_CHECK' $configure 2>/dev/null` + if test $? -eq 0; then + # GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) + params=`echo $macro | sed -e 's/^GTK_DOC_CHECK(\ *\(.*\)).*$/\1/'` + if echo $params | grep -q '^.*\,\ *\[\{0,1\}'; then + extra_options=`echo $params | sed -e 's/^.*\,\ *\[\{0,1\}\([^]]*\)\]\{0,1\}\ *$/\1/'` + #echo >&2 "DEBUG: adding extra options [$extra_options] to [$*]" + set - $* $GTKDOCIZE_FLAGS $extra_options + else + set - $* $GTKDOCIZE_FLAGS + fi + else + no_gtk_doc_check_found=1; + fi +fi + +while test $# -gt 0; do + #echo >&2 "DEBUG: parsing args [$1]"; + case "$1" in + --help) + echo "$usage" + exit 0 ;; + --version) + echo "$PROGRAM ($PACKAGE) $VERSION" + exit 0 ;; + --copy) + copy=yes + shift ;; + --docdir) + shift + docdir="$1" + shift ;; + --docdir=*) + docdir=`expr "X$1" : '[^=]*=\(.*\)'` + shift ;; + --flavour) + shift + flavour="$1" + shift ;; + --flavour=*) + flavour=`expr "X$1" : '[^=]*=\(.*\)'` + shift ;; + --srcdir) + shift + # srcdir was set earlier. + shift ;; + --srcdir=*) + # srcdir was set earlier. + shift ;; + -*) + echo "$progname: unrecognised option '$1'" 1>&2 + echo "$usage" 1>&2 + exit 1 ;; + *) + echo "$progname: too many arguments" 1>&2 + echo "$usage" 1>&2 + exit 1 ;; + esac +done + +case "$flavour" in + legacy-flat|no-tmpl-flat) + makefile=gtk-doc.flat.make + ;; + no-xslt) + makefile=gtk-doc.no-xslt.make + ;; + no-xslt-flat) + makefile=gtk-doc.no-xslt-flat.make + ;; + legacy|no-tmpl) + ;; + *) + echo "$progname: invalid value for --flavour" 1>&2 + echo "$usage" 1>&2 + exit 1 ;; +esac + +if test $no_configure_found -eq 1; then + echo "$progname: neither configure.ac nor configure.in exist" 1>&2 + exit 1 +fi +if test $no_gtk_doc_check_found -eq 1; then + echo "$progname: GTK_DOC_CHECK not called in $configure" 1>&2 + exit 1 +fi + +# If the AC_CONFIG_MACRO_DIR() macro is used, copy gtk-doc.m4 from our +# prefix to that directory. This makes sure that the M4 macro used +# matches the the automake fragment. +# If AC_CONFIG_MACRO_DIR is not used, the macro won't be copied, and +# the correct flags must be passed to aclocal for it to find the macro. +m4dir="$srcdir"/`autoconf 2>/dev/null --trace 'AC_CONFIG_MACRO_DIR:$1' "$configure"` +if test -n "$m4dir"; then + rm -f $m4dir/gtk-doc.m4 + if test "$copy" = yes; then + cp -f $datadir/aclocal/gtk-doc.m4 $m4dir/ || + exit 1 + else + ln -sf $datadir/aclocal/gtk-doc.m4 $m4dir/ || + cp -f $datadir/aclocal/gtk-doc.m4 $m4dir/ || + exit 1 + fi +fi + +rm -f $docdir/gtk-doc.make +if test "$copy" = yes; then + cp -f $datadir/gtk-doc/data/$makefile $docdir/gtk-doc.make || + exit 1 +else + ln -sf $datadir/gtk-doc/data/$makefile $docdir/gtk-doc.make || + cp -f $datadir/gtk-doc/data/$makefile $docdir/gtk-doc.make || + exit 1 +fi diff --git a/gtk-doc-for-gtk4/buildsystems/autotools/meson.build b/gtk-doc-for-gtk4/buildsystems/autotools/meson.build new file mode 100644 index 0000000000..c39d3fb622 --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/autotools/meson.build @@ -0,0 +1,41 @@ +configure_file( + input: 'gtkdocize.in', + output: 'gtkdocize', + configuration: binary_in, + install: true, + install_dir: bindir, +) + +custom_target( + 'gtk-doc.flat.make', + input: 'gtk-doc.make', + output: 'gtk-doc.flat.make', + install: true, + install_dir: pkgdatadir, + capture: true, + command: [ + 'sed', + '-e', + 's/EXTRA_DIST =/EXTRA_DIST +=/', + '@INPUT@', + ] +) + +custom_target( + 'gtk-doc.m4', + input: 'gtk-doc.m4', + output: 'gtk-doc.m4', + install: true, + install_dir: autoconfdatadir, + command: [ + 'cp', + '-f', + '@INPUT@', + '@OUTPUT@', + ], +) + +install_data( + ['gtk-doc.make'], + install_dir: pkgdatadir, +) diff --git a/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfig.cmake b/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfig.cmake new file mode 100644 index 0000000000..e6815a05ac --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfig.cmake @@ -0,0 +1,432 @@ +# CMake macros to use the GtkDoc documentation system +# +# See the GTK-Doc manual (help/manual/C/index.docbook) for an example of how to +# use this. + +# Output variables: +# +# GTKDOC_FOUND ... set to 1 +# +# GTKDOC_SCAN_EXE ... the location of the gtkdoc-scan executable +# GTKDOC_SCANGOBJ_EXE ... the location of the gtkdoc-scangobj executable +# GTKDOC_MKDB_EXE ... the location of the gtkdoc-mkdb executable +# GTKDOC_MKHTML_EXE ... the location of the gtkdoc-mkhtml executable +# GTKDOC_FIXXREF_EXE ... the location of the gtkdoc-fixxref executable + + +#============================================================================= +# Copyright 2009 Rich Wareham +# Copyright 2015 Lautsprecher Teufel GmbH +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +#============================================================================= + +include(CMakeParseArguments) + +set(GTKDOC_FOUND 1) + +find_program(GTKDOC_SCAN_EXE gtkdoc-scan) +find_program(GTKDOC_SCANGOBJ_EXE gtkdoc-scangobj) +find_program(GTKDOC_MKDB_EXE gtkdoc-mkdb) +find_program(GTKDOC_MKHTML_EXE gtkdoc-mkhtml) +find_program(GTKDOC_FIXXREF_EXE gtkdoc-fixxref) + +get_filename_component(_this_dir ${CMAKE_CURRENT_LIST_FILE} PATH) +find_file(GTKDOC_SCANGOBJ_WRAPPER GtkDocScanGObjWrapper.cmake PATH ${_this_dir}) + +# :: +# +# gtk_doc_add_module(doc_prefix +# SOURCE [...] +# XML xmlfile +# [LIBRARIES depend1...] +# [FIXXREFOPTS fixxrefoption1...] +# [IGNOREHEADERS header1...] +# [CONTENT_FILES example1...] +# [SCANOPTS scanoption1...] +# [SCANOBJOPTS scanobjoption1...] +# [MKDBOPTS mkdboption1...] +# [HTMLOPTS htmloption1...]) +# +# Add a module with documentation to be processed with GTK-Doc. +# +# must be the *full* path to the source directory. +# +# If omitted, xmlfile defaults to the auto generated ${doc_prefix}/${doc_prefix}-docs.xml. +# +# The `gtkdoc-scangobj` program is used to get introspection information for +# the module. You should pass the target(s) to be scanned as LIRARIES. This +# will try to set the correct compiler and link flags for the introspection +# build to use, and the correct LD_LIBRARY_PATH for it to run, and the correct +# dependencies for the doc target. +# +# You *can* also set the compile and link flags manually, using the 'CFLAGS' +# and 'LDFLAGS' options. The 'LDPATH' option controls the LD_LIBRARY_PATH. You +# can also manually add additional targets as dependencies of the +# documentation build with the DEPENDS option. +# +# The 'CONTENT_FILES' option is here to copy the files extending the documentation +# such as exemples and custom xml files. +# +# The 'SCANOPTS' option is here to pass arguments to 'gtkdoc-scan' +# The 'SCANOBJOPTS' option is here to pass arguments to 'gtkdoc-scangobj' +# The 'MKDBOPTS' option is here to pass arguments to 'gtkdoc-mkdb' +# The 'HTMLOPTS' option is here to pass arguments to 'gtkdoc-mkhtml' +# +# This function a target named "doc-${doc_prefix}". You will need to manually +# add it to the ALL target if you want it to be built by default, you can do +# something like this: +# +# gtk_doc_add_module(doc-mymodule +# SOURCE ${CMAKE_SOURCE_DIR}/module ${CMAKE_BINARY_DIR}/module +# LIBRARIES mylibrary +# LIBRARY_DIRS ${GLIB_LIBRARY_DIRS} ${FOO_LIBRARY_DIRS} +# add_custom_target(all-documentation ALL) +# add_dependencies(all-documentation doc-mymodule) +# +function(gtk_doc_add_module _doc_prefix) + set(_one_value_args "XML") + set(_multi_value_args "FIXXREFOPTS" "IGNOREHEADERS" "LIBRARIES" "LIBRARY_DIRS" "SOURCE" "SUFFIXES" + "CFLAGS" "DEPENDS" "LDFLAGS" "LDPATH" "CONTENT_FILES" "SCANOPTS" "SCANOBJOPTS" + "MKDBOPTS" "HTMLOPTS") + cmake_parse_arguments("GTK_DOC" "" "${_one_value_args}" "${_multi_value_args}" ${ARGN}) + + if(NOT GTK_DOC_SOURCE) + message(FATAL_ERROR "No SOURCE specified for gtk_doc_add_module ${_doc_prefix}") + endif() + + set(_xml_file ${GTK_DOC_XML}) + + set(_fixxrefopts ${GTK_DOC_FIXXREFOPTS}) + set(_ignore_headers ${GTK_DOC_IGNOREHEADERS}) + set(_libraries ${GTK_DOC_LIBRARIES}) + set(_library_dirs ${GTK_DOC_LIBRARY_DIRS}) + set(_suffixes ${GTK_DOC_SUFFIXES}) + + set(_content_files ${GTK_DOC_CONTENT_FILES}) + set(_scanopts ${GTK_DOC_SCANOPTS}) + set(_scanobjopts ${GTK_DOC_SCANOBJOPTS}) + set(_mkdbopts ${GTK_DOC_MKDBOPTS}) + set(_htmlopts ${GTK_DOC_HTMLOPTS}) + + set(_extra_cflags ${GTK_DOC_CFLAGS}) + set(_depends ${GTK_DOC_DEPENDS}) + set(_extra_ldflags ${GTK_DOC_LDFLAGS}) + set(_extra_ldpath ${GTK_DOC_LDPATH}) + + if(_suffixes) + set(_doc_source_suffixes "") + foreach(_suffix ${_suffixes}) + if(_doc_source_suffixes) + set(_doc_source_suffixes "${_doc_source_suffixes},${_suffix}") + else(_doc_source_suffixes) + set(_doc_source_suffixes "${_suffix}") + endif(_doc_source_suffixes) + endforeach(_suffix) + else(_suffixes) + set(_doc_source_suffixes "h") + endif(_suffixes) + + # Parse the LIBRARIES option and collect compile and link flags for those + # targets. + foreach(target ${_libraries}) + _gtk_doc_get_cflags_for_target(_target_cflags ${target}) + _gtk_doc_get_ldflags_for_target(_target_ldflags ${target} "${_libraries}") + list(APPEND _extra_cflags ${_target_cflags}) + list(APPEND _extra_ldflags ${_target_ldflags}) + list(APPEND _extra_ldpath $) + + list(APPEND _depends ${target}) + endforeach() + + # Link directories can't be specified per target, only for every target + # under a given directory. + get_property(all_library_directories DIRECTORY PROPERTY LINK_DIRECTORIES) + foreach(library_dir ${all_library_directories}) + list(APPEND _extra_ldflags ${CMAKE_LIBRARY_PATH_FLAG}${library_dir}) + list(APPEND _extra_ldpath ${library_dir}) + endforeach() + + list(REMOVE_DUPLICATES _extra_cflags) + list(SORT _extra_cflags) + + list(REMOVE_DUPLICATES _extra_ldflags) + list(SORT _extra_ldflags) + + list(REMOVE_DUPLICATES _extra_ldpath) + list(SORT _extra_ldpath) + + # a directory to store output. + set(_output_dir "${CMAKE_CURRENT_BINARY_DIR}") + set(_output_dir_stamp "${_output_dir}/dir.stamp") + + # set default sgml file if not specified + set(_default_xml_file "${_output_dir}/${_doc_prefix}-docs.xml") + get_filename_component(_default_xml_file ${_default_xml_file} ABSOLUTE) + + # a directory to store html output. + set(_output_html_dir "${_output_dir}/html") + set(_output_html_dir_stamp "${_output_dir}/html_dir.stamp") + + # The output files + set(_output_decl_list "${_output_dir}/${_doc_prefix}-decl-list.txt") + set(_output_decl "${_output_dir}/${_doc_prefix}-decl.txt") + set(_output_overrides "${_output_dir}/${_doc_prefix}-overrides.txt") + set(_output_sections "${_output_dir}/${_doc_prefix}-sections.txt") + set(_output_types "${_output_dir}/${_doc_prefix}.types") + + set(_output_signals "${_output_dir}/${_doc_prefix}.signals") + + set(_output_unused "${_output_dir}/${_doc_prefix}-unused.txt") + set(_output_undeclared "${_output_dir}/${_doc_prefix}-undeclared.txt") + set(_output_undocumented "${_output_dir}/${_doc_prefix}-undocumented.txt") + + set(_output_xml_dir "${_output_dir}/xml") + set(_output_sgml_stamp "${_output_dir}/sgml.stamp") + + set(_output_html_stamp "${_output_dir}/html.stamp") + + # we depend on the content files being there before doing anything + if(_content_files) + list(APPEND _depends ${_content_files}) + endif(_content_files) + + # add a command to create output directory + add_custom_command( + OUTPUT "${_output_dir_stamp}" "${_output_dir}" + COMMAND ${CMAKE_COMMAND} -E make_directory "${_output_dir}" + COMMAND ${CMAKE_COMMAND} -E touch ${_output_dir_stamp} + VERBATIM) + + set(_ignore_headers_opt "") + if(_ignore_headers) + set(_ignore_headers_opt "--ignore-headers=") + foreach(_header ${_ignore_headers}) + set(_ignore_headers_opt "${_ignore_headers_opt}${_header} ") + endforeach(_header ${_ignore_headers}) + endif(_ignore_headers) + + foreach(source_dir ${GTK_DOC_SOURCE}) + set(_source_dirs_opt ${_source_dirs_opt} --source-dir=${source_dir}) + endforeach() + + # add a command to scan the input + add_custom_command( + OUTPUT + "${_output_decl_list}" + "${_output_decl}" + "${_output_overrides}" + "${_output_sections}" + "${_output_types}" + DEPENDS + "${_output_dir_stamp}" + ${_depends} + COMMAND + ${GTKDOC_SCAN_EXE} + --module=${_doc_prefix} + ${_ignore_headers_opt} + ${_source_dirs_opt} + --rebuild-sections + --rebuild-types + ${_scanopts} + WORKING_DIRECTORY ${_output_dir} + VERBATIM) + + # add a command to scan the input via gtkdoc-scangobj + # This is such a disgusting hack! + add_custom_command( + OUTPUT + ${_output_signals} + DEPENDS + ${_output_types} + COMMAND ${CMAKE_COMMAND} + -D "GTKDOC_SCANGOBJ_EXE:STRING=${GTKDOC_SCANGOBJ_EXE}" + -D "_scanobjopts:STRING=${_scanobjopts}" + -D "doc_prefix:STRING=${_doc_prefix}" + -D "output_types:STRING=${_output_types}" + -D "output_dir:STRING=${_output_dir}" + -D "EXTRA_CFLAGS:STRING=${_extra_cflags}" + -D "EXTRA_LDFLAGS:STRING=${_extra_ldflags}" + -D "EXTRA_LDPATH:STRING=${_extra_ldpath}" + -P ${GTKDOC_SCANGOBJ_WRAPPER} + WORKING_DIRECTORY "${_output_dir}" + VERBATIM) + + set(_copy_xml_if_needed "") + if(_xml_file) + get_filename_component(_xml_file ${_xml_file} ABSOLUTE) + set(_copy_xml_if_needed + COMMAND ${CMAKE_COMMAND} -E copy "${_xml_file}" "${_default_xml_file}") + endif(_xml_file) + + set(_remove_xml_if_needed "") + if(_xml_file) + set(_remove_xml_if_needed + COMMAND ${CMAKE_COMMAND} -E remove ${_default_xml_file}) + endif(_xml_file) + + set(_copy_content_files_if_needed "") + if(_content_files) + foreach(_content_file ${_content_files}) + # We need to copy the content files to the build directory. + # We respect the folder tree if the file comes from the current + # source or binary directory but copy the file to the current binary + # directory if it comes from somewhere else. + get_filename_component(_content_file ${_content_file} ABSOLUTE) + string(REGEX MATCH "^${CMAKE_CURRENT_SOURCE_DIR}" _is_in_source ${_content_file}) + string(REGEX MATCH "^${CMAKE_CURRENT_BINARY_DIR}" _is_in_binary ${_content_file}) + if (_is_in_source OR _is_in_binary) + if(_is_in_source) + file(RELATIVE_PATH _content_file_relative ${CMAKE_CURRENT_SOURCE_DIR} ${_content_file}) + else(_is_in_source) + file(RELATIVE_PATH _content_file_relative ${CMAKE_CURRENT_BINARY_DIR} ${_content_file}) + endif(_is_in_source) + set(_content_file_destination + "${_output_dir}/${_content_file_relative}") + else(_is_in_source OR _is_in_binary) + get_filename_component(_content_file_name ${_content_file} NAME) + set(_content_file_destination + "${_output_dir}/${_content_file_name}") + endif(_is_in_source OR _is_in_binary) + get_filename_component(_content_file_destination ${_content_file_destination} ABSOLUTE) + if(NOT ${_content_file_destination} EQUAL ${_content_file}) + set(_copy_content_files_if_needed + ${_copy_content_files_if_needed} + COMMAND ${CMAKE_COMMAND} -E copy "${_content_file}" "${_content_file_destination}") + endif(NOT ${_content_file_destination} EQUAL ${_content_file}) + endforeach(_content_file) + endif(_content_files) + + # add a command to make the database + add_custom_command( + OUTPUT + ${_output_sgml_stamp} + ${_default_xml_file} + DEPENDS + ${_output_types} + ${_output_signals} + ${_output_sections} + ${_output_overrides} + ${_depends} + ${_remove_xml_if_needed} + COMMAND ${CMAKE_COMMAND} -E remove_directory ${_output_xml_dir} + ${_copy_xml_if_needed} + ${_copy_content_files_if_needed} + COMMAND ${GTKDOC_MKDB_EXE} + --module=${_doc_prefix} + ${_source_dirs_opt} + --source-suffixes=${_doc_source_suffixes} + --output-format=xml + --main-sgml-file=${_default_xml_file} + ${_mkdbopts} + WORKING_DIRECTORY "${_output_dir}" + VERBATIM) + + # add a command to create html directory + add_custom_command( + OUTPUT "${_output_html_dir_stamp}" "${_output_html_dir}" + COMMAND ${CMAKE_COMMAND} -E make_directory ${_output_html_dir} + COMMAND ${CMAKE_COMMAND} -E touch ${_output_html_dir_stamp} + VERBATIM) + + # add a command to output HTML + add_custom_command( + OUTPUT + ${_output_html_stamp} + DEPENDS + ${_output_html_dir_stamp} + ${_output_sgml_stamp} + ${_xml_file} + ${_depends} + ${_copy_xml_if_needed} + # The binary dir needs adding to --path in order for mkhtml to pick up + # any version.xml file there might be in there + COMMAND + cd ${_output_html_dir} && ${GTKDOC_MKHTML_EXE} + ${_doc_prefix} + ${_default_xml_file} + ${_htmlopts} + COMMAND + cd ${_output_dir} && ${GTKDOC_FIXXREF_EXE} + --module=${_doc_prefix} + --module-dir=${_output_html_dir} + ${_fixxrefopts} + COMMENT + "Generating HTML documentation for ${_doc_prefix} module with gtkdoc-mkhtml" + VERBATIM) + + add_custom_target(doc-${_doc_prefix} + DEPENDS "${_output_html_stamp}") +endfunction(gtk_doc_add_module) + +# These two functions reimplement some of the core logic of CMake, in order +# to generate compiler and linker flags from the relevant target properties. +# It sucks that we have to do this, but CMake's own code for this doesn't seem +# to be reusable -- there's no way to say "tell me the flags that you would +# pass to a linker for this target". + +function(_gtk_doc_get_cflags_for_target result_var target) + get_target_property(target_definitions ${target} COMPILE_DEFINITIONS) + if(target_definitions) + foreach(target_definition ${target_definitions}) + # We need to prepend -D to the definition flag + list(APPEND cflags -D${target_definition}) + endforeach() + endif() + + get_target_property(target_options ${target} COMPILE_OPTIONS) + if(target_options) + list(APPEND cflags ${target_options}) + endif() + + get_target_property(target_include_dirs ${target} INCLUDE_DIRECTORIES) + foreach(target_include_dir ${target_include_dirs}) + list(APPEND cflags -I${target_include_dir}) + endforeach() + + list(REMOVE_DUPLICATES cflags) + list(SORT cflags) + + set(${result_var} ${cflags} PARENT_SCOPE) +endfunction() + +function(_gtk_doc_get_ldflags_for_target result_var target all_targets) + get_target_property(target_link_flags ${target} LINK_FLAGS) + if(target_link_flags) + list(APPEND ldflags ${target_link_flags}) + endif() + + get_target_property(target_link_libraries ${target} LINK_LIBRARIES) + foreach(target_library ${target_link_libraries}) + # The IN_LIST operator is new in CMake 3.3, so I've tried to avoid using it. + list(FIND all_targets ${target_library} target_library_is_explicit_dependency) + if(NOT ${target_library_is_explicit_dependency} EQUAL -1) + # This target is part of the current project. We will add it to + # LDFLAGS explicitly, so don't try to add it as well. + # In fact, we can't do that, as the containing directory + # probably won't be in the linker search path, and we can't find + # that out and add it ourselves. + else() + list(APPEND ldflags "${target_library}") + endif() + endforeach() + + # Link in the actual target, as well. + list(APPEND ldflags $) + + list(REMOVE_DUPLICATES ldflags) + list(SORT ldflags) + + set(${result_var} ${ldflags} PARENT_SCOPE) +endfunction() diff --git a/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfigVersion.cmake.in b/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfigVersion.cmake.in new file mode 100644 index 0000000000..9d74050861 --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocConfigVersion.cmake.in @@ -0,0 +1,13 @@ +# CMake package version configuration file for GTK-Doc. + +set(PACKAGE_VERSION @PACKAGE_VERSION@) + +# Check whether the requested PACKAGE_FIND_VERSION is compatible +if("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}") + set(PACKAGE_VERSION_COMPATIBLE FALSE) +else() + set(PACKAGE_VERSION_COMPATIBLE TRUE) + if ("${PACKAGE_VERSION}" VERSION_EQUAL "${PACKAGE_FIND_VERSION}") + set(PACKAGE_VERSION_EXACT TRUE) + endif() +endif() diff --git a/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocScanGObjWrapper.cmake b/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocScanGObjWrapper.cmake new file mode 100644 index 0000000000..b187ebb2d0 --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/cmake/GtkDocScanGObjWrapper.cmake @@ -0,0 +1,68 @@ +# Internal -- for use with UseGtkDoc.cmake +# +#============================================================================= +# Copyright 2009 Rich Wareham +# Copyright 2015 Lautsprecher Teufel GmbH +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +#============================================================================= + +# This is needed for find_package(PkgConfig) to work correctly -- +# CMAKE_MINIMUM_REQUIRED_VERSION needs to be defined. +cmake_minimum_required(VERSION 3.2) + +if(NOT APPLE) + # We use pkg-config to find glib et al + find_package(PkgConfig) + # Find glib et al + pkg_check_modules(GLIB REQUIRED glib-2.0 gobject-2.0) + +foreach(_flag ${EXTRA_CFLAGS} ${GLIB_CFLAGS}) + set(ENV{CFLAGS} "$ENV{CFLAGS} '${_flag}'") +endforeach(_flag) + +foreach(_flag ${EXTRA_LDFLAGS} ${GLIB_LDFLAGS}) + set(ENV{LDFLAGS} "$ENV{LDFLAGS} '${_flag}'") +endforeach(_flag) + +foreach(_flag ${EXTRA_LDPATH}) + if(DEFINED ENV{LD_LIBRARY_PATH}) + set(ENV{LD_LIBRARY_PATH} "$ENV{LD_LIBRARY_PATH}:${_flag}") + else(DEFINED ENV{LD_LIBRARY_PATH}) + set(ENV{LD_LIBRARY_PATH} "${_flag}") + endif(DEFINED ENV{LD_LIBRARY_PATH}) +endforeach(_flag) + +message(STATUS "Executing gtkdoc-scangobj with:") +message(STATUS " CFLAGS: $ENV{CFLAGS}") +message(STATUS " LDFLAGS: $ENV{LDFLAGS}") +message(STATUS " LDPATH: $ENV{LD_LIBRARY_PATH}") + +execute_process(COMMAND ${GTKDOC_SCANGOBJ_EXE} + "--module=${doc_prefix}" + "--types=${output_types}" + "--output-dir=${output_dir}" + ${_scanobjopts} + WORKING_DIRECTORY "${output_dir}" + RESULT_VARIABLE _scan_result) + +if(_scan_result EQUAL 0) + message(STATUS "Scan succeeded.") +else(_scan_result EQUAL 0) + message(SEND_ERROR "Scan failed.") +endif(_scan_result EQUAL 0) + +endif(NOT APPLE) + +# vim:sw=4:ts=4:et:autoindent diff --git a/gtk-doc-for-gtk4/buildsystems/cmake/Makefile.am b/gtk-doc-for-gtk4/buildsystems/cmake/Makefile.am new file mode 100644 index 0000000000..a11e89b529 --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/cmake/Makefile.am @@ -0,0 +1,15 @@ +EXTRA_DIST = \ + GtkDocConfig.cmake \ + GtkDocConfigVersion.cmake.in \ + GtkDocScanGObjWrapper.cmake + +CLEANFILES = \ + GtkDocConfigVersion.cmake + +cmakedir = $(datadir)/cmake/GtkDoc +cmake_DATA = \ + GtkDocConfig.cmake \ + GtkDocConfigVersion.cmake \ + GtkDocScanGObjWrapper.cmake + +-include $(top_srcdir)/git.mk diff --git a/gtk-doc-for-gtk4/buildsystems/cmake/meson.build b/gtk-doc-for-gtk4/buildsystems/cmake/meson.build new file mode 100644 index 0000000000..2ba754581f --- /dev/null +++ b/gtk-doc-for-gtk4/buildsystems/cmake/meson.build @@ -0,0 +1,26 @@ +cmake_in = configuration_data() +cmake_in.set('PACKAGE_VERSION', version) + +configure_file( + input: 'GtkDocConfigVersion.cmake.in', + output: 'GtkDocConfigVersion.cmake', + configuration: cmake_in, + install: true, + install_dir: join_paths( + cmakedatadir, + 'GtkDoc', + ) +) + +gtkdoc_cmake_data = [ + 'GtkDocConfig.cmake', + 'GtkDocScanGObjWrapper.cmake', +] + +install_data( + gtkdoc_cmake_data, + install_dir: join_paths( + cmakedatadir, + 'GtkDoc', + ) +) diff --git a/gtk-doc-for-gtk4/configure.ac b/gtk-doc-for-gtk4/configure.ac new file mode 100644 index 0000000000..f242c80c16 --- /dev/null +++ b/gtk-doc-for-gtk4/configure.ac @@ -0,0 +1,221 @@ +dnl Process this file with autoconf to produce a configure script. +AC_PREREQ([2.63]) + +dnl We're using a two digit number for the releases and +dnl a three digit number for the development version +m4_define(gtk_doc_version, 1.32.1) + +AC_INIT([gtk-doc],[gtk_doc_version],[https://gitlab.gnome.org/GNOME/gtk-doc/issues],[gtk-doc]) + +AC_CONFIG_MACRO_DIR([m4]) +AC_CONFIG_SRCDIR([gtk-doc.pc.in]) +AC_CONFIG_AUX_DIR([build-aux]) + +AM_INIT_AUTOMAKE([1.11 check-news std-options -Wno-portability tar-ustar no-dist-gzip dist-xz]) +AM_MAINTAINER_MODE([enable]) + +# Support silent build rules, requires at least automake-1.11. Disable +# by either passing --disable-silent-rules to configure or passing V=1 +# to make +AM_SILENT_RULES([yes]) + +# Check for programs +AC_PROG_CC + +# Initialize libtool +LT_PREREQ([2.2]) +LT_INIT + +dnl Make sure we have pkg-config >= 0.19, so installing in $(datadir) is OK. +PKG_PROG_PKG_CONFIG([0.19]) + +dnl +dnl Check for Python. +dnl +AM_PATH_PYTHON([3.2]) + +dnl +dnl Check for xsltproc +dnl +AC_PATH_PROG([XSLTPROC], [xsltproc]) +if test -z "$XSLTPROC"; then + AC_MSG_ERROR([xsltproc not found]) +fi + +dnl +dnl Check for dblatex/fop (for pdf output) +dnl +AC_PATH_PROG([DBLATEX], [dblatex]) +if test -z "$DBLATEX"; then + AC_PATH_PROG([FOP], [fop]) + if test -z "$FOP"; then + AC_MSG_WARN([neither dblatex nor fop found, so no pdf output from xml]) + fi +fi + +dnl check for DocBook DTD and stylesheets in the local catalog. +JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.3//EN], [DocBook XML DTD V4.3]) +JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl], [DocBook XSL Stylesheets]) + +dnl +dnl Set runtime package dirs so we can find the script containing common routines. +dnl +dnl From Autoconf Macro Archive: +m4_define([AC_DEFINE_DIR], [ + prefix_NONE= + exec_prefix_NONE= + test "x$prefix" = xNONE && prefix_NONE=yes && prefix=$ac_default_prefix + test "x$exec_prefix" = xNONE && exec_prefix_NONE=yes && exec_prefix=$prefix + eval ac_define_dir="\"[$]$2\"" + eval ac_define_dir="\"$ac_define_dir\"" + AC_SUBST($1, "$ac_define_dir") + test "$prefix_NONE" && prefix=NONE + test "$exec_prefix_NONE" && exec_prefix=NONE +]) +PACKAGE_DATA_DIR="${datadir}/${PACKAGE}/data" +AC_DEFINE_DIR([PACKAGE_DATA_DIR], [PACKAGE_DATA_DIR]) +PYTHON_PACKAGE_DIR="${datadir}/${PACKAGE}/python" +AC_DEFINE_DIR([PYTHON_PACKAGE_DIR], [PYTHON_PACKAGE_DIR]) + +dnl Only use -Wall if we have gcc +if test "x$GCC" = "xyes"; then + if test -z "`echo "$CFLAGS" | grep "\-Wall" 2> /dev/null`" ; then + CFLAGS="$CFLAGS -Wall" + fi +fi + +dnl if glib is available we can enable the tests +PKG_CHECK_MODULES(TEST_DEPS, [glib-2.0 >= 2.6.0 gobject-2.0 >= 2.6.0], + [ glib_prefix="`$PKG_CONFIG --variable=prefix glib-2.0`" + gtk_doc_use_libtool="yes" + build_tests="yes" + ], + [ gtk_doc_use_libtool="no" + build_tests="no" + ] +) +AM_CONDITIONAL(GTK_DOC_USE_LIBTOOL, test -n "$LIBTOOL" -a x$gtk_doc_use_libtool = xyes ) +dnl this enables the rule in test/Makefile.am +AM_CONDITIONAL(BUILD_TESTS, test x$build_tests = xyes) +AC_SUBST(glib_prefix) + +dnl enable runtime debugging code +AC_MSG_CHECKING(whether to enable runtime debugging code) +AC_ARG_ENABLE([debug], + AS_HELP_STRING([--enable-debug], + [enable runtime debugging code (default=no)]),, + [enable_debug="no"]) +AC_MSG_RESULT($enable_debug) + +dnl check what date format we can use for the makefile tracing in tests +dnl this is mostly to detect the date command on macosx that is quite cripled +dnl and broken too +AC_MSG_CHECKING(whether date can output nanoseconds) +date +%s.%N | grep -q 'N' +if test "$?" = "1"; then + TS_FMT="+%s.%N" + ELAPSED_FMT="+%H:%M:%S.%N" + AC_MSG_RESULT(yes) +else + TS_FMT="+%s.0" + ELAPSED_FMT="+%H:%M:%S" + AC_MSG_RESULT(no) +fi +AC_SUBST(TS_FMT) +AC_SUBST(ELAPSED_FMT) + +AC_MSG_CHECKING(whether date can format dates) +date >/dev/null 2>&1 --utc --date @1.1 $ELAPSED_FMT +if test "$?" = "0"; then + DATE_FMT_CMD="date --utc $ELAPSED_FMT --date @0" + AC_MSG_RESULT(yes) +else + DATE_FMT_CMD="echo " + AC_MSG_RESULT(no) +fi +AC_SUBST(DATE_FMT_CMD) + +dnl +dnl Documentation +dnl +AC_MSG_CHECKING([for yelp-tools]) +have_yelp_tools=no +m4_ifdef([YELP_HELP_INIT],[ +AC_MSG_RESULT([yes]) +YELP_HELP_INIT +have_yelp_tools=yes +]) +if test "x$have_yelp_tools" != "xyes"; then + AC_MSG_RESULT([no]) +fi +AM_CONDITIONAL([HAVE_YELP_TOOLS],[test x$have_yelp_tools = xyes]) + +dnl +dnl Python modules +dnl +AX_PYTHON_MODULE("pygments") + +AC_CONFIG_FILES([Makefile +gtk-doc.pc +buildsystems/autotools/Makefile +buildsystems/cmake/Makefile +buildsystems/cmake/GtkDocConfigVersion.cmake +gtkdoc/config_data.py +help/Makefile +help/manual/Makefile +tests/Makefile +tests/annotations/Makefile +tests/annotations/src/Makefile +tests/annotations/docs/Makefile +tests/bugs/Makefile +tests/bugs/src/Makefile +tests/bugs/docs/Makefile +tests/empty/Makefile +tests/empty/src/Makefile +tests/empty/docs/Makefile +tests/fail/Makefile +tests/fail/src/Makefile +tests/fail/docs/Makefile +tests/gobject/Makefile +tests/gobject/src/Makefile +tests/gobject/docs/Makefile +tests/program/Makefile +tests/program/src/Makefile +tests/program/docs/Makefile +tests/repro/Makefile +tests/repro/src/Makefile +tests/repro/docs/Makefile +]) + +dnl run chmod on these after parsing them. +AC_CONFIG_FILES([gtkdoc-check], [chmod +x gtkdoc-check]) +AC_CONFIG_FILES([gtkdoc-depscan], [chmod +x gtkdoc-depscan]) +AC_CONFIG_FILES([gtkdoc-fixxref], [chmod +x gtkdoc-fixxref]) +AC_CONFIG_FILES([gtkdoc-mkdb], [chmod +x gtkdoc-mkdb]) +AC_CONFIG_FILES([gtkdoc-mkhtml], [chmod +x gtkdoc-mkhtml]) +AC_CONFIG_FILES([gtkdoc-mkhtml2], [chmod +x gtkdoc-mkhtml2]) +AC_CONFIG_FILES([gtkdoc-mkman], [chmod +x gtkdoc-mkman]) +AC_CONFIG_FILES([gtkdoc-mkpdf], [chmod +x gtkdoc-mkpdf]) +AC_CONFIG_FILES([gtkdoc-rebase], [chmod +x gtkdoc-rebase]) +AC_CONFIG_FILES([gtkdoc-scan], [chmod +x gtkdoc-scan]) +AC_CONFIG_FILES([gtkdoc-scangobj], [chmod +x gtkdoc-scangobj]) +AC_CONFIG_FILES([buildsystems/autotools/gtkdocize], [chmod +x buildsystems/autotools/gtkdocize]) +AC_CONFIG_FILES([tests/tools.sh], [chmod +x tests/tools.sh]) +AC_OUTPUT + +AC_MSG_NOTICE([ +gtk-doc was configured with the following options: +==================================================]) + +test -n "$DBLATEX$FOP" \ + && AC_MSG_NOTICE([** PDF support enabled, using $DBLATEX$FOP]) \ + || AC_MSG_NOTICE([ PDF support disabled, no dblatex or fop available]) +test "x$build_tests" != "xno" \ + && AC_MSG_NOTICE([** Building regression tests]) \ + || AC_MSG_NOTICE([ Skipping regression tests]) +test "x$enable_debug" != "xno" \ + && AC_MSG_NOTICE([** Debug tracing enabled]) \ + || AC_MSG_NOTICE([ Debug tracing disabled]) +test "x$have_yelp_tools" != "xno" \ + && AC_MSG_NOTICE([** Documentation enabled]) \ + || AC_MSG_NOTICE([ Documentation disabled]) diff --git a/gtk-doc-for-gtk4/devhelp2.xsd b/gtk-doc-for-gtk4/devhelp2.xsd new file mode 100644 index 0000000000..899630de56 --- /dev/null +++ b/gtk-doc-for-gtk4/devhelp2.xsd @@ -0,0 +1,217 @@ + + + + + + + Devhelp2 files are use in the 'devhelp' documentation browser. + + + + + + + Known keyword types. + + + + + + + + + + + + + + + + + + + + + Known programming languages. + + + + + + + + + + + + + + + + + + + Sub tags for the hierarchy of the chapters and parts. + + + + + + + + + + + + + + + The chapters tag encloses the structure of the reference manual. Each + sub unit is represented by a sub tag. + + + + + + + + + + + + + The keyword tag points to the documentation of a api symbol. + + + + + + + Type of the keyword. + + + + + + + Keyword name. + + + + + + + Relative link for the keyword. + + + + + + + Version since that the keyword is part of the API. + + + + + + + Marks the keyword as deprecated. + + + + + + + Document the stability status. + + + + + + + + + + The functions tag encloses all api symbols of the reference manual. Each + sub unit is represented by a keyword tag. + + + + + + + + + + + + + Toplevel element of a devhelp book. A devhelp book list the structure of + a developer manual together with development related metadata. + + + + + + + + + + + Title of the reference manual. + + + + + + + Entry point to the manual. Can be given as a relative path to the + location of the devhelp2 file. + + + + + + + Author of the document. Multiple authors are separated by ','. + + + + + + + Short name of the manual. + + + + + + + Version of the devhelp xml specification (2). + + + + + + + Programming language this manual refers to. + + + + + + + URL for the online version of the docs. + + + + + + diff --git a/gtk-doc-for-gtk4/devhelp2.xsl b/gtk-doc-for-gtk4/devhelp2.xsl new file mode 100644 index 0000000000..37c235a032 --- /dev/null +++ b/gtk-doc-for-gtk4/devhelp2.xsl @@ -0,0 +1,173 @@ + + + + + + + + + + + + book + + + .devhelp2 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + , + + + + + diff --git a/gtk-doc-for-gtk4/doc/README b/gtk-doc-for-gtk4/doc/README new file mode 100644 index 0000000000..f0636d6378 --- /dev/null +++ b/gtk-doc-for-gtk4/doc/README @@ -0,0 +1,27 @@ +Note +==== + +There is now a user manual which can be read using yelp and can be found under +'development'. Please refer to this documentation for up-to-date information. + + +Files +===== + +setting-up.txt + 5-step guide to setting up a module to use gtk-doc. + +gnome.txt + information on the source code comments format which the Gnome project + has just started to use. + +sections-file.txt + describes the MODULE-sections.txt file which is used to organise the + documentation. + +style-guide.txt + Initial draft of a style guide for writing GTK+ docs. + +authors.txt + notes for authors of the GTK documentation. The abbreviations to use, + a few useful DocBook tags etc. diff --git a/gtk-doc-for-gtk4/doc/authors.txt b/gtk-doc-for-gtk4/doc/authors.txt new file mode 100644 index 0000000000..b46b41c831 --- /dev/null +++ b/gtk-doc-for-gtk4/doc/authors.txt @@ -0,0 +1,151 @@ +Note +==== + +There is now a user manual which can be read using yelp and can be found under +'development'. Please refer to this documentation for up-to-date information. + + +General +======= + +The files to edit manually are generated in the tmpl/ directory. +Remember to use < or > instead of '<' and '>', in these files. + +The first part of each function/macro/struct etc. description should be +a very short summary of what it is. This may be used at some point to +produce a short reference guide which can be printed out. + +For macros which return a value just like a function, you must manually +add a '@Returns: ' field. + +You may want to rearrange the functions/macros etc. to split them into +related sections. To do this rearrange the MODULE-sections.txt +files. You can also add between functions. Currently this just +results in a blank line between them in the synopsis. + +If a function or macro has a very long description, you may want the table +of parameters to go somewhere in the middle rather than after the description +as would normally happen. To place the table of parameters in the middle of +the description simple write "" on its own line at the +desired location. + + +Abbreviations +============= + +These are expanded into appropriate DocBook tags, saving a lot of typing. +I've used the Gnome ones (see gnome.txt) but also added '#'. + + Use function() to refer to functions or macros which take arguments. + + Use @param to refer to parameters. (I've also used this when referring to + parameters of other functions, related to the one being described.) + + Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS. + + Use #symbol to refer to other types of symbol, e.g. structs and enums + and macros which don't take arguments. + + + +Useful DocBook Tags +=================== + +These are the DocBook tags which I have used or I think could be useful. +Let me know if I'm doing something wrong! + + +To link to another section in the GTK docs: + + Hash Tables + + The linkend is the SGML id on the top item of the page you want to link to. + For most pages this is currently the part ("gtk", "gdk", glib") and then + the page title ("Hash Tables"). For widgets it is just the class name. + Spaces and underscores are converted to '-' to conform to SGML. + + +To refer to an external function, e.g. a standard C function: + + ... + + +To include example code: + + + Using a GHashTable. + + ... + + + + or possibly this, for very short code fragments which don't need a title: + + + + ... + + + + +To include bulleted lists: + + + + + + ... + + + + + + ... + + + + + + +To include a note which stands out from the text: + + + + Make sure you free the data after use. + + + +To refer to a type: + + unsigned char + + +To refer to an external structure (not one described in the GTK docs): + + XFontStruct + + +To refer to a field of a structure: + + len + + +To refer to a class name, we could possibly use: + + GtkWidget + + but you'll probably be using #GtkWidget instead (to automatically create + a link to the GtkWidget page - see the abbreviations above). + + +To emphasize text: + + This is important + + but I haven't been using it so far. + + +For filenames use: + + c:\windows + diff --git a/gtk-doc-for-gtk4/doc/design-1.x.txt b/gtk-doc-for-gtk4/doc/design-1.x.txt new file mode 100644 index 0000000000..4e7fbc95c2 --- /dev/null +++ b/gtk-doc-for-gtk4/doc/design-1.x.txt @@ -0,0 +1,28 @@ += gtk-doc-1.X = +This document attempts to reverse engineer some design decisions in +gtk-doc-1.X. + +== sgml-ids == +When creating SGML IDS, we append ":CAPS" to all +all-caps identifiers to prevent name clashes (SGML ids are case-insensitive). +(It basically never is the case that mixed-case identifiers would collide.) + +Unfortunately we create ambiguous ids. The document structure ids are e.g. +GtkWidget.{top_of_page,synopsis,object-hierarchy,...} +and that is ambiguous with eventual structure member of the same name. + +cd tests +find . -name "*.xml" -exec grep -o "id=\"[a-zA-Z_:.\-]*\"" {} \; | sort | uniq + +== section-ids == +gtk-doc differentiates between plain-sections and gobject-sections: ++---------+----------------+ +| type | section-id | ++---------+----------------+ +| plain | $module-$title | +| gobject | $title | ++---------+----------------+ + +- links to #GtkWidget would go to $title +- linking to the struct would need #GtkWidget-struct + diff --git a/gtk-doc-for-gtk4/doc/design-2.x.txt b/gtk-doc-for-gtk4/doc/design-2.x.txt new file mode 100644 index 0000000000..0f4abed5da --- /dev/null +++ b/gtk-doc-for-gtk4/doc/design-2.x.txt @@ -0,0 +1,173 @@ += gtk-doc-2.X = +This documents purpose is to collect what needs to be changed for a potential +gtk-doc-2.X. + +== name == +Its not about Gtk. Its about C APIs with GObject support. But it is probably not +worth it. +g-doc, gapi-doc, gnome-api-doc, ... + +== remove and deprecate = +- tree_index and object_index are still named *.sgml +- in the makefiles + sgml-build.stamp -> db-build.stamp + sgml.stamp -> db.stamp + +== design fixes == +=== proper xml-id namespaces === +We need proper xml-id namespaces for document structure and symbols to avoid +clashes e.g. between GtkWidget as a section and as a struct. Normal symbols +should only be mangled to be a valid xml-id. Document structure ids should +contain a prefix. + +These are the rules regarding id-attributes: + +http://www.w3.org/TR/html4/types.html#type-id: +"ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by + any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons + (":"), and periods (".")." + +http://www.w3.org/TR/xml-id/#id-avn +"Attributes of type ID are subject to additional normalization rules: removing + leading and trailing space characters and replacing sequences of spaces with a + single space." + +http://www.w3.org/TR/xml11/#NT-Name +http://www.w3.org/TR/REC-xml/#NT-Name + +So we could easily use "DOC:" as a prefix for document structure ids. +In 1.x we add :CAPS as a suffix to avoid clashes between lower and uppercase +constructs. XML-IDs are not case insensitive, so we don't need that. + +If the ID contain a ':' xml processors believe it is using a namespace. + +=== less files to maintain === +- one needs to maintain $module-docs.xml +- in most cases $module-sections.txt need manual maintenance + - we could have a "Section:" tag for non-section comments to add them to a non + default section + - we could have a "Private_Symbols:" tag in section to list symbols that + should be in private subsection +- the $module.types file need manual maintenance if one need special includes + - can we make the scanner smarter? + +=== srcdir != builddir builds === +- all tools get a search path + - it contains builddir:srcdir if those are different or just one of them if + they are the same + - all files we read are checked through the path + - all files are written based on the first entry + +=== build dependencies === + +=== error/warning reporting === +- don't fail the build on doc-issues, instead fail the tests +- all diagnostic output from the tools run during build in gcc style +- instead of having -{undocumented,undeclared,unused}.txt have just one file + 'doc-module.log' + - contains all the build diagnostics as well + - summary as 'INFO' level +- gtkdoc-check will scan that file for 'ERROR'/'WARNING' lines + - depending on the CHECK_OPTIONS and the found lines if will fail certain + tests + +- TODO + - recheck all output and check whether we need Warnings/Errors or just + Warnings and flags to silence them + - Do we need a way to suppress false positives? + +=== docbook -> markdown === +The main performance culprit is the use of docbook (tools). Also writing docbook +in source comments is cumbersome. Finally the docbook toolchain is a heavy +dependency and harms portability. We already support lots of markdown, so we'd +like to have a pure markdown based workflow. + +For that we'd like to provide a migration path: +- convert existing docbook files to markdown (e.g. using pandoc) +- convert/identify comments using docbook to markdown + +Next we would replace gtkdoc-mkdb+gtkdoc-fixxref with gtkdoc-mkhtml2. This would +output html directly. + +We could change gtkdoc-mkpdf to use wkhtmltopdf/htmldoc. For man-pages we +can use https://rtomayko.github.io/ronn/ronn.1.html. +The devhelp2 files would be output directly from gtkdoc-mkhtml2. + +We can enable this new toolchain via the configure flavors option (needs support +for cmake, meson, ...). + +These would be the steps to do this: +1.) [in progress] write the docbook comment migation tool: +see tools: tools/db2md.py +At the same time improve the amount of markdown we handle: +* or _: +** or __: +but be careful with already existing '*' and '_' chars (check warnings in +tools/db2md.py). + +2.) [unassigned] create the plumbing for the new tool chain +Add the new makefile flavour to run gtkdoc-mkhtml2 instead. Add --flavour +options for gtkdocize. Create a stub gtkdoc-mkhtml2 tool. + +3.) [in progress] refactor gtkdoc/mkdb.py to extract reusable code +- gtkdoc/md_to_db.py + - only have the parse there + +4.) [unassigned] write gtkdoc/mkhtml2.py +- select a template engine (e.g. jinja) +- create templates from the current html for the various page types (refentry, + index, ...). +- we won't need content_files and expand_content_files in Makefile.am, as + mkhtml2 would read $(DOC_MODULE)-docs.md (rename to index.md?) and find local + links in there +- convert all hand-written md files starting from the main-doc to html + +Open Issues: +wkhtmltopdf html/*.html tester2.pdf +Error: This version of wkhtmltopdf is build against an unpatched version of QT, and does not support more then one input document. + +htmldoc --book --outfile tester2.pdf html/*.html +- need to pass html files in the logical order +- unicode issues (passing --charset utf-8 fails) +- --link seems to create bad links (opens file-browser) +- no css rendering :/ + +pandoc -r docbook -w markdown_github -o tester-docs.md tester-docs.xml +- pandoc has no xi:include support +- if we pipe it through xmllint we convert everything. +xmllint --noent --xinclude tester-docs.xml | pandoc -r docbook -w markdown -o tester-docs.md +- the index.md would need to represent the structure the docbook chunker would + create + +gdbus-codegen: +- add an option to generate markdown comments + +gstreamer plugindocs: +- generate markdown formatted files + +=== only drop docbook-xsl === +Since the processing with docbook-xsl is what is slow, we could also consider to +keep the whole gtkdoc-mkdb and have 2 codepaths in gtkdoc-mkhtml. The new code- +path would real the docbook with element-tree, replicate the chunking that +docbook-xsl does and use a templating system to generate the html files +(e.g. jinja). + +This is probably easier to achieve, but has less potential in the long run (e.g. +incremental doc updates). + +On the plus side, we can do rarely used output-formats (like pdf, man) the way +we do them right now. + +These would be the steps to do this: +1.) [done] write a the chunker +- standalone tool to load the docbook xml and chunk it (just touch the resulting + *.html files) until we produce the same + +2.) [unassigned] transform some docbook to html +- evaluate template engines + - jinja2: + - we can use the block syntax to handle nesting +- we need to warn when not handling certain docbook + +3.) [unassigned] integrate this into the gtkdoc library +- add an option to gtkgoc-mkhtml (e.g. --engine={xslt,builtin} or just --noxlst) diff --git a/gtk-doc-for-gtk4/doc/gnome.txt b/gtk-doc-for-gtk4/doc/gnome.txt new file mode 100644 index 0000000000..8ebffa1c27 --- /dev/null +++ b/gtk-doc-for-gtk4/doc/gnome.txt @@ -0,0 +1,84 @@ +Note +==== + +There is now a user manual which can be read using yelp and can be found under +'development'. Please refer to this documentation for up-to-date information. + + +HowTo +===== + +These are the comment blocks used in Gnome source files to document +functions (and macros, signals and properties, if you want). + +/** + * function_name: + * @par1: description of parameter 1. These can extend over more than + * one line. + * @par2: description of parameter 2 + * + * The function description goes here. You can use @par1 to refer to parameters + * so that they are highlighted in the output. You can also use %constant + * for constants, function_name2() for functions and #GtkWidget for links to + * other declarations (which may be documented elsewhere). + * + * Returns: an integer. + */ + +The block starts with '/**'. +Each line starts with ' * '. + +The second line is the function name, optionally followed by a ':'. In +order to document signals in inline comments, use a name of the form +class::signal, e.g. GtkWidget::notify-child. For properties, use a +name of the form class:property, e.g. GtkAlignment:top-padding. Note +that gtk-doc expects the signal and property names to be spelled with +hyphens, not underlines. + +Following the function name are the parameters, e.g. '@par1:' above. + +A blank line MUST be used to separate parameter descriptions from the main +description (otherwise it is assumed to be a continuation of the parameter +description.) + +After the main description is a 'Returns:' line to describe the +returned value of the function (if it is not void). + +Text inside the descriptions can use these special characters (they +will be expanded into appropriate DocBook tags): + + @name a parameter. + %name a constant. + name() reference to a function, or a macro which works like a function + (this will be turned into a hypertext link if the function is + documented anywhere). + #name reference to any other type of declaration, e.g. a struct, enum, + union, or macro (this will also be turned into a link if possible). + +To avoid problems, the characters '<', '>' and '&' in the descriptions are +converted into the SGML entities < > and &. +This means that you can't use Docbook SGML tags, unless specify the --sgml-mode +option for gtkdoc-mkdb, which suppresses the escaping of '<', '>' and +'&' and allows Docbook markup in inline comments. + +If you are using markup in inline comments, you must be careful to to +not run into problems with the automatic splitting of the comment in +paragraphs at empty lines. A line counts as empty for this purpose, if +it is empty after the removal of the initial ' * ' prefix. Thus you +can work around this problem by adding some trailing whitespace to +lines which should appear as empty, but not end a paragraph. This is +especially relevant in code examples, which often contain empty lines. + +Some more hints regarding examples: Hyperlinks in the formatted examples +are confusing, therefore you should suppress the gtk-doc markup by using +function() instead of function(). Use character entities to refer +to the characters %, &, < or #, e.g. + + if (a < b && verbose) + printf ("bla %s %#x", bla, a); + +would become + + if (a < b && verbose) + printf ("bla %s %#x", bla, a); + diff --git a/gtk-doc-for-gtk4/doc/gtkdoc.dot b/gtk-doc-for-gtk4/doc/gtkdoc.dot new file mode 100644 index 0000000000..a5fd24095e --- /dev/null +++ b/gtk-doc-for-gtk4/doc/gtkdoc.dot @@ -0,0 +1,80 @@ +/* files and tools in gtk-doc workflow + * dot -Tpng gtkdoc.dot -ogtkdoc.png + */ + +digraph gtkdoc { + /* graph attributes */ + /*rankdir=BT;*/ + + /* default node attributes */ + node [ shape=box]; + + /* tools nodes */ + gtkdoc_scan [label="gtkdoc-scan",shape="ellipse" ]; + gtkdoc_scangobj [label="gtkdoc-scangobj",shape="ellipse" ]; + gtkdoc_mkdb [label="gtkdoc-mkdb",shape="ellipse" ]; + gtkdoc_mkhtml [label="gtkdoc-mkhtml",shape="ellipse" ]; + gtkdoc_fixxref [label="gtkdoc-fixxref",shape="ellipse" ]; + gtkdoc_rebase [label="gtkdoc-rebase",shape="ellipse" ]; + gtkdoc_check [label="gtkdoc-check",shape="ellipse" ]; + + /* file nodes */ + headers [label="headers\nall headers under DOC_SOURCE_DIR\n+EXTRA_HFILES\n-IGNORE_HFILES"]; + sources [label="source code\nall files under DOC_SOURCE_DIR\nmatching SUFFIXES or *.{c,h}"]; + binary [label="compiled binary"]; + xml [label="docbook xml"]; + html [label="html"]; + module_decl_list [label="*-decl-list.txt" ]; + module_decl [label="*-decl.txt" ]; + module_types [label="*.types" ]; + module_sections [label="*-section.txt" ]; + module_signals [label="*.signals" ]; + module_hierarchy [label="*.hierarchy" ]; + module_interfaces [label="*.interfaces" ]; + module_prerequisites [label="*.prerequisites" ]; + module_args [label="*.args" ]; + module_undeclared [label="*-undeclared.txt" ]; + module_undocumented [label="*-undocumented.txt" ]; + module_unused [label="*-unused.txt" ]; + + /* tool invocation */ + gtkdoc_scan -> gtkdoc_scangobj -> gtkdoc_mkdb -> gtkdoc_mkhtml -> gtkdoc_fixxref -> gtkdoc_rebase -> gtkdoc_check [style="dotted"]; + + /* file usage */ + headers -> gtkdoc_scan; + gtkdoc_scan -> module_sections [label="--rebuild-sections", style="dashed"]; + gtkdoc_scan -> module_types [label="--rebuild-types", style="dashed"]; + gtkdoc_scan -> module_decl; + gtkdoc_scan -> module_decl_list; + + binary -> gtkdoc_scangobj; + module_types -> gtkdoc_scangobj; + gtkdoc_scangobj -> module_signals; + gtkdoc_scangobj -> module_hierarchy; + gtkdoc_scangobj -> module_interfaces; + gtkdoc_scangobj -> module_prerequisites; + gtkdoc_scangobj -> module_args; + + sources -> gtkdoc_mkdb; + module_sections -> gtkdoc_mkdb; + module_decl -> gtkdoc_mkdb; + module_signals -> gtkdoc_mkdb; + module_args -> gtkdoc_mkdb; + module_hierarchy -> gtkdoc_mkdb; + module_interfaces -> gtkdoc_mkdb; + module_prerequisites -> gtkdoc_mkdb; + gtkdoc_mkdb -> xml; + gtkdoc_mkdb -> module_undeclared; + gtkdoc_mkdb -> module_undocumented; + gtkdoc_mkdb -> module_unused; + + xml -> gtkdoc_mkhtml -> html; + + html -> gtkdoc_fixxref -> html; + html -> gtkdoc_rebase -> html; + + module_undeclared -> gtkdoc_check; + module_undocumented -> gtkdoc_check; + module_unused -> gtkdoc_check; +} + diff --git a/gtk-doc-for-gtk4/doc/sections-file.txt b/gtk-doc-for-gtk4/doc/sections-file.txt new file mode 100644 index 0000000000..235d6e8cb2 --- /dev/null +++ b/gtk-doc-for-gtk4/doc/sections-file.txt @@ -0,0 +1,66 @@ +Note +==== + +There is now a user manual which can be read using yelp and can be found under +'development'. Please refer to this documentation for up-to-date information. + + +*-section.txt +============= + +This describes the MODULE-sections.txt file which is used to organise the +documentation output by gtk-doc. + +The file is divided into sections. Each section will be output to a separate +file in the templates, which also corresponds to a SGML file, and a file in +the final HTML files. Each section contains a list of function/macro etc. +names, which can be rearranged into the desired order. + +The ... tag is used to specify the file name, without any +suffix. For example, using 'gnome-config' will result in the +section declarations being output in the template file tmpl/gnome-config.sgml, +which will be converted into the DocBook SGML file sgml/gnome-config.sgml. +(The name of the html file is based on the module name and the section title, +or for widgets it is based on the widget name converted to lower case). + +The ... tag is used to specify the title of the section. +It is only useful before the templates are initially created, since the title +set in the template file overrides this. + +You can group items in the section by using the tag. Currently +it outputs a blank line between subsections in the synopsis section. +You can also use for standard GtkObject declarations +(e.g. the functions like gtk_object_get_type and macros like GTK_OBJECT(), +GTK_IS_OBJECT() etc.) Currently these are left out of the documentation. +You can also use for private declarations which will not +be output (Its a handy way to avoid warning messages about unused +declarations.). If your library contains private types which you don't want +to appear in the object hierarchy and the list of implemented or required +interfaces, add them to a Private subsection. + +You can also use ... to specify the #include files which +are shown in the synopsis sections. It contains a comma-separate list of +#include files, without the angle brackets. If you set it outside of any +sections, it acts for all sections until the end of the file. If you set it +within a section, it only applies to that section. + +If a line starts with a '#' it is treated as a comment and ignored. + +Example MODULE-sections.txt file: + +# This is a comment. +gnome.h + +
+gnome-dateedit +GnomeDateEdit +gnome_date_edit_new +gnome_date_edit_set_time +gnome_date_edit_set_popup_range +gnome_date_edit_get_date + +GNOME_DATE_EDIT +GNOME_IS_DATE_EDIT +gnome_date_edit_get_type +GNOME_DATE_EDIT_CLASS +
diff --git a/gtk-doc-for-gtk4/doc/setting-up.txt b/gtk-doc-for-gtk4/doc/setting-up.txt new file mode 100644 index 0000000000..d3a6e5ba80 --- /dev/null +++ b/gtk-doc-for-gtk4/doc/setting-up.txt @@ -0,0 +1,86 @@ +Note +==== + +There is now a user manual which can be read using yelp and can be found under +'development'. Please refer to this documentation for up-to-date information. + + +How to Set Up an Application or Library to use GTK-Doc +====================================================== + +This assumes that you are using autoconf & automake to build your package, +and already have gtk-doc installed properly. + + +1. Add this line to your autogen.sh, before the calls to autoheader, automake + or autoconf: + + gtkdocize || exit 1 + + If you are using gnome-autogen.sh it already runs gtkdocize for you. + If you don't have an autogen.sh script you may need to run gtkdocize + manually. (All gtkdocize does is copy gtk-doc.make to your project.) + + +2. Add this line to your configure.in (somewhere before the call to AC_OUTPUT) + + GTK_DOC_CHECK(1.0) + + The number in brackets is the minimum version of gtk-doc required. + + +3. Create a directory in your project where you want the docs to be built, + e.g. 'myproject/docs/reference'. If you want to create several separate + pieces of documentation you can create subdirectories for each one here. + (e.g. GTK+ has subdirectories for gtk, gdk and gdk-pixbuf.) + + +4. Copy examples/Makefile.am to this directory (or subdirectories) and edit + the variables at the top of the file. (See the GTK+ source for an example.) + + +5. Add the new Makefile(s) to your configure.in's AC_OUTPUT call, and make sure + all the SUBDIRS variables are set properly so the docs directory is built. + + +6. If your library or application includes GtkObjects/GObjects, and you want + their signals, arguments/parameters and position in the hierarchy to be + documented: + + Create a MODULE.types file in the docs directory, e.g. "myproject.types". + This should contain any '#include' directives needed to compile a program + with your module, and a list of functions to initialize all of the widgets + and objects in the library. For example, the gtk.types file starts like + this: + + #include + + gtk_accel_label_get_type + gtk_adjustment_get_type + gtk_alignment_get_type + gtk_arrow_get_type + +============================================================================= + +That's it! If you now build the application or library you should get a +complete set of documentation. gtk-doc is normally off by default so you +may have to pass '--enable-gtk-doc' to autogen.sh or configure.in. + +(Note that due to a problem with make the build may fail the very first time +it is run, but if you run make again it should work. It only fails because +there are no files in the tmpl/ directory initially. As soon as these are +created it works fine.) + + +You can tweak the output in several ways: + + o modify the main SGML file to add introductory sections or to split the + documentation into several chapters. + + o modify the MODULE-sections.txt file to rearrange the documentation into + different sections or a different order (see sections-file.txt for info). + + o add a MODULE-overrides.txt to override particular declarations. + + +Damon diff --git a/gtk-doc-for-gtk4/doc/style-guide.txt b/gtk-doc-for-gtk4/doc/style-guide.txt new file mode 100644 index 0000000000..59da5e4f06 --- /dev/null +++ b/gtk-doc-for-gtk4/doc/style-guide.txt @@ -0,0 +1,234 @@ +Note +==== + +There is now a user manual which can be read using yelp and can be found under +'development'. Please refer to this documentation for up-to-date information. + + +NOTE: This is only a draft version. Don't make major changes to your + documentation until we've agreed on all this. + + +GTK+ Reference Documentation Style Guide +======================================== + +This file describes the way the GTK+ reference documentation should be written, +so that we produce consistent documentation. + +We will also designate one or two of the template files as 'model' templates, +i.e. they are to be taken as the 'correct' way to write the documentation: + + GtkFontSelectionDialog - contains example code and descriptions of enums. + GtkMisc - contains description of fields in a widget struct. + + +Language +======== + +Use American spelling rather than British, i.e. color rather than colour, +organize rather than organise etc. + +End all descriptions of functions & parameters with a period '.'. + + +Organizing Sections +=================== + +The organization of the sections is determined by the glib-sections.txt, +gdk-sections.txt and gtk-sections.txt files. + +Group related functions/macros/enums etc. and place a "" tag +(on its own line) between groups. This results in a blank line in the synopsis +between the groups, which makes it a bit easier to read. + +Order the groups sections by placing the most important/commonly-used +functions/macros etc. first. For pairs of accessor functions place them +together with the 'get' function first and then the 'set' function. + +Private functions etc. should be placed at the end of the "
", +after a "" line. They will not appear in the HTML output +and they do not have to be documented (they will disappear form the template +files the next time 'make templates' is run). + +Enumerations should appear after the first function which uses them. + + +Section Descriptions +=================== + +For widgets, start the main description with - + + + +The #GtkFontSelectionDialog widget ... + + +If you want to include subsections in the main description, to conform to +DocBook SGML you must have 0 or more leading paragraphs (or possibly other +DocBook tags - see the DTD), then 1 or more subsections, with +nothing after. e.g. + + + +Introduction to the section.... + + + First Subsection + + This is the first subsection. + + + + Second Subsection + + This is the second subsection. + + + + +Functions & Macro Descriptions +============================== + +Start the description with a phrase like this: + 'Looks up a key in a GHashTable'. +i.e. assume that 'This function' (or 'This macro') precedes it. + + +Function Parameters +=================== + +For object-oriented code, denote the object parameter with 'a', +e.g. 'a #GHashTable'. + +Use 'the' for the rest of the parameters. + + +Widget Structs +============== + +Some widget structs have fields which are useful to the developer, since +there are currently no accessor functions to retrieve the particular field. + +These fields should be documented as follows: + +----------------------------------------------------------------------- + + +The #GtkFixedChild-struct struct contains the following fields. +(These fields should be considered read-only. They should never be set by +an application.) + + +@widget: the child #GtkWidget. +@x: the horizontal position of the widget within the #GtkFixed + container. +@y: the vertical position of the widget within the #GtkFixed + container. +----------------------------------------------------------------------- + + +If a widget struct is completely private, use this: + +----------------------------------------------------------------------- + + +The #GtkFontSelectionDialog-struct struct contains private data only, and +should be accessed using the functions below. + +----------------------------------------------------------------------- + +Note that the links to the widget names go to the top of the page, +e.g. links to #GtkAccelLabel result in a link to the GtkAccelLabel page. +If you want to link to the widget struct, you must append '-struct', +e.g. #GtkAccelLabel-struct + +Whether a particular field in a structure is output in the +documentation is determined by adding /*< public >*/ and +/*< private >*/ comments into the header files. For instance, +GtkEditable looks like: + +----------------------------------------------------------------------- +struct _GtkEditable +{ + GtkWidget widget; + + /*< public >*/ + guint current_pos; + + guint selection_start_pos; + guint selection_end_pos; + guint has_selection : 1; + + /*< private >*/ + guint editable : 1; + guint visible : 1; + GdkIC *ic; + GdkICAttr *ic_attr; + + gchar *clipboard_text; +}; +----------------------------------------------------------------------- + +You should add these as you go along. Please send these changes +in along with your patches for the reference docs. Widget structures +are by default all private, other structures are by default all public. + + +Enumerations +============ + +A lot of the enumerations in GTK+ are currently placed in the "Standard +Enumerations" section. However, some of these are specific to a particular +widget and so should be moved to the widget's section and documented there. + +The enumeration values should be documented as follows: + +----------------------------------------------------------------------- + + +A set of bit flags used to specify the filter being set +when calling gtk_font_selection_dialog_set_filter() or +gtk_font_selection_set_filter(). + + +@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user. +@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the 'Filter' page + of the #GtkFontSelection widget. +----------------------------------------------------------------------- + + +See Also +======== + +To link to related widgets/pages, use a like below. +If there aren't any related pages, simply leave the See_Also section as it is, +and it will not be output. +Note that ancestors of widgets may automatically be added here, so +don't add them yourself. + +----------------------------------------------------------------------- + + + + + +#GtkFontSelection +the underlying widget for selecting fonts. + + + + +----------------------------------------------------------------------- + + +Including Hypertext Links +========================= + +Use the tag to include hypertext links, e.g. + +Gnome's home page is at www.gnome.org. + +Remember that the documentation may be printed, so it is probably best +to repeat the URL within the link. + +Damon, 1 June 1999 diff --git a/gtk-doc-for-gtk4/examples/Makefile.am b/gtk-doc-for-gtk4/examples/Makefile.am new file mode 100644 index 0000000000..1c0d907818 --- /dev/null +++ b/gtk-doc-for-gtk4/examples/Makefile.am @@ -0,0 +1,111 @@ +# -*- mode: makefile -*- +# +# Makefile.am - template makefile for gtk-doc module +# Copyright (C) 2007-2017 Stefan Sauer +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +# +# As a special exception, the above copyright owner gives unlimited +# permission to copy, distribute and modify this Makefile.am template. +# You need not follow the terms of the GNU General Public License when +# using or distributing such Makefile.am files, even though portions of +# the text of the Makefile.am appear in them. The GNU General Public +# License (GPL) does govern all other use of the material that constitutes +# the Makefile.am template. + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE= + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 + +# The top-level XML file. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml + +# Directories containing the source code. +# gtk-doc will search all .c and .h files beneath these paths +# for inline comments documenting functions and macros. +# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk +DOC_SOURCE_DIR= + +# Extra options to pass to gtkdoc-scangobj. Normally not needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb +# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml +MKDB_OPTIONS=--xml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Normally not needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB= +CFILE_GLOB= + +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +EXTRA_HFILES= + +# Header files or dirs to ignore when scanning. Use base file/dir names +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code +IGNORE_HFILES= + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.xml building.xml changes-2.0.xml +content_files= + +# Files where gtk-doc abbreviations (#GtkWidget) are expanded +# e.g. expand_content_files=running.xml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS= +GTKDOC_LIBS= + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Comment this out if you don't want 'make check' to test you doc status +# and run some sanity checks +if ENABLE_GTK_DOC +TESTS_ENVIRONMENT = \ + DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ + SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) +TESTS = $(GTKDOC_CHECK) +endif + +-include $(top_srcdir)/git.mk diff --git a/gtk-doc-for-gtk4/examples/README b/gtk-doc-for-gtk4/examples/README new file mode 100644 index 0000000000..c0a5815cca --- /dev/null +++ b/gtk-doc-for-gtk4/examples/README @@ -0,0 +1,9 @@ + +The Makefile.am here should be copied to your project's API documentation +directory, and the variables edited appropriately. + +See doc/setting-up.txt for documentation on setting up a project to use +gtk-doc. + +See the GTK+ and libglade sources for example Makefile.am option settings. + diff --git a/gtk-doc-for-gtk4/git.mk b/gtk-doc-for-gtk4/git.mk new file mode 100644 index 0000000000..9d4bf2511e --- /dev/null +++ b/gtk-doc-for-gtk4/git.mk @@ -0,0 +1,333 @@ +# git.mk, a small Makefile to autogenerate .gitignore files +# for autotools-based projects. +# +# Copyright 2009, Red Hat, Inc. +# Copyright 2010,2011,2012,2013 Behdad Esfahbod +# Written by Behdad Esfahbod +# +# Copying and distribution of this file, with or without modification, +# is permitted in any medium without royalty provided the copyright +# notice and this notice are preserved. +# +# The latest version of this file can be downloaded from: +GIT_MK_URL = https://raw.githubusercontent.com/behdad/git.mk/master/git.mk +# +# Bugs, etc, should be reported upstream at: +# https://github.com/behdad/git.mk +# +# To use in your project, import this file in your git repo's toplevel, +# then do "make -f git.mk". This modifies all Makefile.am files in +# your project to -include git.mk. Remember to add that line to new +# Makefile.am files you create in your project, or just rerun the +# "make -f git.mk". +# +# This enables automatic .gitignore generation. If you need to ignore +# more files, add them to the GITIGNOREFILES variable in your Makefile.am. +# But think twice before doing that. If a file has to be in .gitignore, +# chances are very high that it's a generated file and should be in one +# of MOSTLYCLEANFILES, CLEANFILES, DISTCLEANFILES, or MAINTAINERCLEANFILES. +# +# The only case that you need to manually add a file to GITIGNOREFILES is +# when remove files in one of mostlyclean-local, clean-local, distclean-local, +# or maintainer-clean-local make targets. +# +# Note that for files like editor backup, etc, there are better places to +# ignore them. See "man gitignore". +# +# If "make maintainer-clean" removes the files but they are not recognized +# by this script (that is, if "git status" shows untracked files still), send +# me the output of "git status" as well as your Makefile.am and Makefile for +# the directories involved and I'll diagnose. +# +# For a list of toplevel files that should be in MAINTAINERCLEANFILES, see +# Makefile.am.sample in the git.mk git repo. +# +# Don't EXTRA_DIST this file. It is supposed to only live in git clones, +# not tarballs. It serves no useful purpose in tarballs and clutters the +# build dir. +# +# This file knows how to handle autoconf, automake, libtool, gtk-doc, +# gnome-doc-utils, yelp.m4, mallard, intltool, gsettings, dejagnu, appdata, +# appstream. +# +# This makefile provides the following targets: +# +# - all: "make all" will build all gitignore files. +# - gitignore: makes all gitignore files in the current dir and subdirs. +# - .gitignore: make gitignore file for the current dir. +# - gitignore-recurse: makes all gitignore files in the subdirs. +# +# KNOWN ISSUES: +# +# - Recursive configure doesn't work as $(top_srcdir)/git.mk inside the +# submodule doesn't find us. If you have configure.{in,ac} files in +# subdirs, add a proxy git.mk file in those dirs that simply does: +# "include $(top_srcdir)/../git.mk". Add more ..'s to your taste. +# And add those files to git. See vte/gnome-pty-helper/git.mk for +# example. +# + + + +############################################################################### +# Variables user modules may want to add to toplevel MAINTAINERCLEANFILES: +############################################################################### + +# +# Most autotools-using modules should be fine including this variable in their +# toplevel MAINTAINERCLEANFILES: +GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL = \ + $(srcdir)/aclocal.m4 \ + $(srcdir)/autoscan.log \ + $(srcdir)/configure.scan \ + `AUX_DIR=$(srcdir)/$$(cd $(top_srcdir); $(AUTOCONF) --trace 'AC_CONFIG_AUX_DIR:$$1' ./configure.ac); \ + test "x$$AUX_DIR" = "x$(srcdir)/" && AUX_DIR=$(srcdir); \ + for x in \ + ar-lib \ + compile \ + config.guess \ + config.sub \ + depcomp \ + install-sh \ + ltmain.sh \ + missing \ + mkinstalldirs \ + test-driver \ + ylwrap \ + ; do echo "$$AUX_DIR/$$x"; done` \ + `cd $(top_srcdir); $(AUTOCONF) --trace 'AC_CONFIG_HEADERS:$$1' ./configure.ac | \ + head -n 1 | while read f; do echo "$(srcdir)/$$f.in"; done` +# +# All modules should also be fine including the following variable, which +# removes automake-generated Makefile.in files: +GITIGNORE_MAINTAINERCLEANFILES_MAKEFILE_IN = \ + `cd $(top_srcdir); $(AUTOCONF) --trace 'AC_CONFIG_FILES:$$1' ./configure.ac | \ + while read f; do \ + case $$f in Makefile|*/Makefile) \ + test -f "$(srcdir)/$$f.am" && echo "$(srcdir)/$$f.in";; esac; \ + done` +# +# Modules that use libtool and use AC_CONFIG_MACRO_DIR() may also include this, +# though it's harmless to include regardless. +GITIGNORE_MAINTAINERCLEANFILES_M4_LIBTOOL = \ + `MACRO_DIR=$(srcdir)/$$(cd $(top_srcdir); $(AUTOCONF) --trace 'AC_CONFIG_MACRO_DIR:$$1' ./configure.ac); \ + if test "x$$MACRO_DIR" != "x$(srcdir)/"; then \ + for x in \ + libtool.m4 \ + ltoptions.m4 \ + ltsugar.m4 \ + ltversion.m4 \ + lt~obsolete.m4 \ + ; do echo "$$MACRO_DIR/$$x"; done; \ + fi` + + + +############################################################################### +# Default rule is to install ourselves in all Makefile.am files: +############################################################################### + +git-all: git-mk-install + +git-mk-install: + @echo "Installing git makefile" + @any_failed=; \ + find "`test -z "$(top_srcdir)" && echo . || echo "$(top_srcdir)"`" -name Makefile.am | while read x; do \ + if grep 'include .*/git.mk' $$x >/dev/null; then \ + echo "$$x already includes git.mk"; \ + else \ + failed=; \ + echo "Updating $$x"; \ + { cat $$x; \ + echo ''; \ + echo '-include $$(top_srcdir)/git.mk'; \ + } > $$x.tmp || failed=1; \ + if test x$$failed = x; then \ + mv $$x.tmp $$x || failed=1; \ + fi; \ + if test x$$failed = x; then : else \ + echo "Failed updating $$x"; >&2 \ + any_failed=1; \ + fi; \ + fi; done; test -z "$$any_failed" + +git-mk-update: + wget $(GIT_MK_URL) -O $(top_srcdir)/git.mk + +.PHONY: git-all git-mk-install git-mk-update + + + +############################################################################### +# Actual .gitignore generation: +############################################################################### + +$(srcdir)/.gitignore: Makefile.am $(top_srcdir)/git.mk + @echo "git.mk: Generating $@" + @{ \ + if test "x$(DOC_MODULE)" = x -o "x$(DOC_MAIN_SGML_FILE)" = x; then :; else \ + for x in \ + $(DOC_MODULE)-decl-list.txt \ + $(DOC_MODULE)-decl.txt \ + tmpl/$(DOC_MODULE)-unused.sgml \ + "tmpl/*.bak" \ + xml html \ + ; do echo "/$$x"; done; \ + FLAVOR=$$(cd $(top_srcdir); $(AUTOCONF) --trace 'GTK_DOC_CHECK:$$2' ./configure.ac); \ + case $$FLAVOR in *no-tmpl*) echo /tmpl;; esac; \ + fi; \ + if test "x$(DOC_MODULE)$(DOC_ID)" = x -o "x$(DOC_LINGUAS)" = x; then :; else \ + for lc in $(DOC_LINGUAS); do \ + for x in \ + $(if $(DOC_MODULE),$(DOC_MODULE).xml) \ + $(DOC_PAGES) \ + $(DOC_INCLUDES) \ + ; do echo "/$$lc/$$x"; done; \ + done; \ + for x in \ + $(_DOC_OMF_ALL) \ + $(_DOC_DSK_ALL) \ + $(_DOC_HTML_ALL) \ + $(_DOC_MOFILES) \ + $(DOC_H_FILE) \ + "*/.xml2po.mo" \ + "*/*.omf.out" \ + ; do echo /$$x; done; \ + fi; \ + if test "x$(HELP_ID)" = x -o "x$(HELP_LINGUAS)" = x; then :; else \ + for lc in $(HELP_LINGUAS); do \ + for x in \ + $(HELP_FILES) \ + "$$lc.stamp" \ + "$$lc.mo" \ + ; do echo "/$$lc/$$x"; done; \ + done; \ + fi; \ + if test "x$(gsettings_SCHEMAS)" = x; then :; else \ + for x in \ + $(gsettings_SCHEMAS:.xml=.valid) \ + $(gsettings__enum_file) \ + ; do echo "/$$x"; done; \ + fi; \ + if test "x$(appdata_XML)" = x; then :; else \ + for x in \ + $(appdata_XML:.xml=.valid) \ + ; do echo "/$$x"; done; \ + fi; \ + if test "x$(appstream_XML)" = x; then :; else \ + for x in \ + $(appstream_XML:.xml=.valid) \ + ; do echo "/$$x"; done; \ + fi; \ + if test -f $(srcdir)/po/Makefile.in.in; then \ + for x in \ + po/Makefile.in.in \ + po/Makefile.in.in~ \ + po/Makefile.in \ + po/Makefile \ + po/Makevars.template \ + po/POTFILES \ + po/Rules-quot \ + po/stamp-it \ + po/.intltool-merge-cache \ + "po/*.gmo" \ + "po/*.header" \ + "po/*.mo" \ + "po/*.sed" \ + "po/*.sin" \ + po/$(GETTEXT_PACKAGE).pot \ + intltool-extract.in \ + intltool-merge.in \ + intltool-update.in \ + ; do echo "/$$x"; done; \ + fi; \ + if test -f $(srcdir)/configure; then \ + for x in \ + autom4te.cache \ + configure \ + config.h \ + stamp-h1 \ + libtool \ + config.lt \ + ; do echo "/$$x"; done; \ + fi; \ + if test "x$(DEJATOOL)" = x; then :; else \ + for x in \ + $(DEJATOOL) \ + ; do echo "/$$x.sum"; echo "/$$x.log"; done; \ + echo /site.exp; \ + fi; \ + if test "x$(am__dirstamp)" = x; then :; else \ + echo "$(am__dirstamp)"; \ + fi; \ + if test "x$(LTCOMPILE)" = x -a "x$(LTCXXCOMPILE)" = x -a "x$(GTKDOC_RUN)" = x; then :; else \ + for x in \ + "*.lo" \ + ".libs" "_libs" \ + ; do echo "$$x"; done; \ + fi; \ + for x in \ + .gitignore \ + $(GITIGNOREFILES) \ + $(CLEANFILES) \ + $(PROGRAMS) $(check_PROGRAMS) $(EXTRA_PROGRAMS) \ + $(LIBRARIES) $(check_LIBRARIES) $(EXTRA_LIBRARIES) \ + $(LTLIBRARIES) $(check_LTLIBRARIES) $(EXTRA_LTLIBRARIES) \ + so_locations \ + $(MOSTLYCLEANFILES) \ + $(TEST_LOGS) \ + $(TEST_LOGS:.log=.trs) \ + $(TEST_SUITE_LOG) \ + $(TESTS:=.test) \ + "*.gcda" \ + "*.gcno" \ + $(DISTCLEANFILES) \ + $(am__CONFIG_DISTCLEAN_FILES) \ + $(CONFIG_CLEAN_FILES) \ + TAGS ID GTAGS GRTAGS GSYMS GPATH tags \ + "*.tab.c" \ + $(MAINTAINERCLEANFILES) \ + $(BUILT_SOURCES) \ + $(patsubst %.vala,%.c,$(filter %.vala,$(SOURCES))) \ + $(filter %_vala.stamp,$(DIST_COMMON)) \ + $(filter %.vapi,$(DIST_COMMON)) \ + $(filter $(addprefix %,$(notdir $(patsubst %.vapi,%.h,$(filter %.vapi,$(DIST_COMMON))))),$(DIST_COMMON)) \ + Makefile \ + Makefile.in \ + "*.orig" \ + "*.rej" \ + "*.bak" \ + "*~" \ + ".*.sw[nop]" \ + ".dirstamp" \ + ; do echo "/$$x"; done; \ + for x in \ + "*.$(OBJEXT)" \ + $(DEPDIR) \ + ; do echo "$$x"; done; \ + } | \ + sed "s@^/`echo "$(srcdir)" | sed 's/\(.\)/[\1]/g'`/@/@" | \ + sed 's@/[.]/@/@g' | \ + LC_ALL=C sort | uniq > $@.tmp && \ + mv $@.tmp $@; + +all: $(srcdir)/.gitignore gitignore-recurse-maybe +gitignore: $(srcdir)/.gitignore gitignore-recurse + +gitignore-recurse-maybe: + @for subdir in $(DIST_SUBDIRS); do \ + case " $(SUBDIRS) " in \ + *" $$subdir "*) :;; \ + *) test "$$subdir" = . -o -e "$$subdir/.git" || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) gitignore || echo "Skipping $$subdir");; \ + esac; \ + done +gitignore-recurse: + @for subdir in $(DIST_SUBDIRS); do \ + test "$$subdir" = . -o -e "$$subdir/.git" || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) gitignore || echo "Skipping $$subdir"); \ + done + +maintainer-clean: gitignore-clean +gitignore-clean: + -rm -f $(srcdir)/.gitignore + +.PHONY: gitignore-clean gitignore gitignore-recurse gitignore-recurse-maybe diff --git a/gtk-doc-for-gtk4/gtk-doc-fo.xsl b/gtk-doc-for-gtk4/gtk-doc-fo.xsl new file mode 100644 index 0000000000..da415e180f --- /dev/null +++ b/gtk-doc-for-gtk4/gtk-doc-fo.xsl @@ -0,0 +1,35 @@ + + + + + + + + + 7pt + always + + + + + + #D0D0D0 + 0.5pt + solid + #575757 + 3pt + + + + + + blue + inherit + + + + + + diff --git a/gtk-doc-for-gtk4/gtk-doc.doap b/gtk-doc-for-gtk4/gtk-doc.doap new file mode 100644 index 0000000000..e7d745c3ec --- /dev/null +++ b/gtk-doc-for-gtk4/gtk-doc.doap @@ -0,0 +1,39 @@ + + + gtk-doc + + Documentation generator for C code. + GTK-Doc is used to document C code. +It is typically used to document the public +API of libraries, such as the GTK+ and GNOME libraries, but it can also be +used to document application code. + + + + + + + + + C + Shell + + + + Stefan Sauer + + stefkost + + + + + Matthias Clasen + + matthiasc + + + diff --git a/gtk-doc-for-gtk4/gtk-doc.pc.in b/gtk-doc-for-gtk4/gtk-doc.pc.in new file mode 100644 index 0000000000..fbce7211f9 --- /dev/null +++ b/gtk-doc-for-gtk4/gtk-doc.pc.in @@ -0,0 +1,7 @@ +prefix=@prefix@ +exec_prefix=@exec_prefix@ +data_dir=@datadir@/@PACKAGE@/data + +Name: gtk-doc +Description: API documentation generator +Version: @VERSION@ diff --git a/gtk-doc-for-gtk4/gtk-doc.xsl b/gtk-doc-for-gtk4/gtk-doc.xsl new file mode 100644 index 0000000000..7d6530b138 --- /dev/null +++ b/gtk-doc-for-gtk4/gtk-doc.xsl @@ -0,0 +1,836 @@ + + + + + + + + + + + + + + + + 2 + + book toc + chapter toc + glossary toc + index toc + part toc + reference toc + + 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + en + + + + + + + + + + + + + + + + + + + No "en" localization of " + + " exists. + + + + + + + + bullet + + + + + + + + + + No "en" localization of dingbat + + exists; using "en". + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 1 + 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 1.36 + + + + +FATAL-ERROR: You need the DocBook XSL Stylesheets version 1.36 or higher +to build the documentation. +Get a newer version at http://docbook.sourceforge.net/projects/xsl/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + <xsl:copy-of select="$title"/>: <xsl:apply-templates select="$home" mode="object.title.markup"/> + + + + + + + + + + + +
+
+ + + Generated by GTK-Doc V + + + Generated by GTK-Doc + + +
+ + + +
78267 minNorthomas@apestaart.orgRESOFIXEautogen.sh doesn't take --prefix and similar to configure
+# 147641 +# +# nor +# Nor +# Linu +# GStreamer +# RESO +# FIXE +# [docs] pydoc segfaults when viewing gst package doc +#
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 1.66 + + + + + + + + + + + + 1.66 + + + + + + + + + + +
+
+ +
+
+ + + + + + + + + + + + +
+ +
+ + + + +
+ + + +
+ + + +

+ + + +

+ + +

+ + + + + + + + +

+ + +

+ +

+ 		+ + + + + + + + + + +
+
+ + + + + + + + em-dash + + + + + + + + + idx + + + + + + gls + + + + + + + + + + + + + [  +   |  + + + + +   ] + + + + + + + + + + + + + + + + + + + + + + + + + + + In gtk-doc.xsl: For acronym () no value found! + + + + http://foldoc.org/ + + + + + + + + + + + + + + + + + + diff --git a/gtk-doc-for-gtk4/gtkdoc-check.in b/gtk-doc-for-gtk4/gtkdoc-check.in new file mode 100755 index 0000000000..d9e2ad500d --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-check.in @@ -0,0 +1,41 @@ +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2007 David Nečas +# 2007-2017 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, check, config + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-check version %s - run documentation unit tests' % config.version) + parser.add_argument('--version', action='version', version=config.version) + options = parser.parse_args() + + common.setup_logging() + + sys.exit(check.run(options)) diff --git a/gtk-doc-for-gtk4/gtkdoc-depscan.in b/gtk-doc-for-gtk4/gtkdoc-depscan.in new file mode 100755 index 0000000000..9bfaf302e5 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-depscan.in @@ -0,0 +1,404 @@ +#!@PYTHON@ + +from __future__ import print_function + +import gzip, os.path, re + +from os import environ, popen, walk +from optparse import OptionParser +from sys import stderr + +from xml.sax import ContentHandler, make_parser +from xml.sax.handler import feature_external_ges + +default_books = ['atk', 'gdk', 'gdk-pixbuf', 'glib', 'gio', 'gobject', 'gtk', 'pango'] + +__comment_regex = re.compile(r'/\*.*?\*/', re.DOTALL) +__word_regex = re.compile(r'\b[A-Za-z_][A-Za-z0-9_]*\b') + +u2a_table = { 0x2018:0x27, 0x2019:0x27, 0x201C:0x22, 0x201D:0x22 } + +class Book(object): + def __init__(self, name, folders, version=None): + self.__catalog = None + self.__name = name + self.__symbols = None + self.__timestamp = 0 + self.__title = None + self.__version = version + + for f in folders: + catalogs = map( + lambda n: os.path.join(f, name, n % name), + ['%s.devhelp2', '%s.devhelp2.gz']) + catalogs = map( + lambda n: (os.path.getmtime(n), n), + filter(os.path.isfile, catalogs)) + + catalogs.sort() + + if catalogs: + self.__catalog = catalogs[-1][1] + break + + if not self.__catalog: + raise IOError('No devhelp book found for "%s"' % name) + + def __cmp__(self, other): + if isinstance(other, Book): + return cmp(self.name, other.name) + + return 0 + + def __repr__(self): + return '' % self.__name + + def parse(self): + timestamp = os.path.getmtime(self.__catalog) + + if not self.__symbols or timestamp > self.__timestamp: + class DevhelpContentHandler(ContentHandler): + def __init__(self, book, symbols): + self.__book = book + self.__symbols = symbols + + def startElement(self, name, attrs): + if 'book' == name: + self.title = attrs.get('title') + return + + if 'keyword' == name: + symbol = Symbol.from_xml(self.__book, attrs) + if symbol: self.__symbols[symbol.name] = symbol + return + + self.__symbols, self.__timestamp = dict(), timestamp + handler = DevhelpContentHandler(self, self.__symbols) + + parser = make_parser() + parser.setFeature(feature_external_ges, False) + parser.setContentHandler(handler) + + if self.__catalog.endswith('.gz'): + parser.parse(gzip.open(self.__catalog)) + + else: + parser.parse(open(self.__catalog)) + + self.__title = handler.title + + def _get_symbols(self): + self.parse(); return self.__symbols + def _get_title(self): + self.parse(); return self.__title + + def find_requirements(self): + requirements = dict() + + for symbol in self.symbols.values(): + if not symbol.matches: + continue + + if symbol.since and symbol.since > self.version: + symbol_list = requirements.get(symbol.since, []) + requirements[symbol.since] = symbol_list + symbol_list.append(symbol) + + return requirements + + catalog = property(lambda self: self.__catalog) + name = property(lambda self: self.__name) + version = property(lambda self: self.__version) + + symbols = property(_get_symbols) + title = property(_get_title) + +class Symbol(object): + known_attributes = ('name', 'type', 'link', 'deprecated', 'since') + + class DeprecationInfo(object): + def __init__(self, text): + if text.count(':'): + pair = text.split(':', 1) + + self.__version = Symbol.VersionInfo(pair[0]) + self.__details = pair[1].strip() + + else: + self.__version = None + self.__details = text.strip() + + def __cmp__(self, other): + if isinstance(other, Symbol.DeprecationInfo): + return cmp(self.version, other.version) + + if isinstance(other, Symbol.VersionInfo): + return cmp(self.version, other) + + return 1 + + def __str__(self): + if not self.__version: + return self.__details and str(self.__details) or 'Deprecated' + + if self.__details: + return 'Since %s: %s' % (self.__version, self.__details) + + return 'Since %s' % self.__version + + details = property(lambda self: self.__details) + version = property(lambda self: self.__version) + + class VersionInfo(object): + def __init__(self, text): + match = re.match(r'^\w*\s*((?:\d+\.)*\d+)', text) + + self.__numbers = map(int, match.group(1).split('.')) + self.__hash = reduce(lambda x, y: x * 1000 + y, reversed(self.__numbers)) + self.__text = text.strip() + + def __get_number(self, index): + if len(self.__numbers) > index: + return self.__numbers[index] + + return 0 + + def __cmp__(self, other): + if isinstance(other, Symbol.VersionInfo): + return cmp(self.numbers, other.numbers) + + return 1 + + def __hash__(self): + return self.__hash + + def __repr__(self): + return '.'.join(map(str, self.__numbers)) + + major = property(lambda self: self.__get_number(0)) + minor = property(lambda self: self.__get_number(1)) + patch = property(lambda self: self.__get_number(2)) + numbers = property(lambda self: self.__numbers) + text = property(lambda self: self.__text) + + @classmethod + def from_xml(cls, book, attrs): + name, type, link, deprecated, since = map(attrs.get, Symbol.known_attributes) + + name = name.strip().translate(u2a_table) + + if name.endswith('()'): + if not type in ('function', 'macro'): + type = (name[0].islower() and 'function' or 'macro') + + name = name[:-2].strip() + + words = name.split(' ') + + if len(words) > 1: + if words[0] in ('enum', 'struct', 'union'): + if not type: type = words[0] + name = name[len(words[0]):].strip() + elif 'property' == words[-1]: + assert('The' == words[0]) + owner = link.split('#', 1)[1].split('-', 1)[0] + type, name = 'property', '%s::%s' % (owner, name.split('"')[1]) + elif 'signal' == words[-1]: + assert('The' == words[0]) + owner = link.split('#', 1)[1].split('-', 1)[0] + type, name = 'signal', '%s:%s' % (owner, name.split('"')[1]) + + if not type: return None + + if None != deprecated: deprecated = Symbol.DeprecationInfo(deprecated) + if since: since = Symbol.VersionInfo(since) + + if name.count(' '): + print >>stderr, ( + 'WARNING: Malformed symbol name: "%s" (type=%s) in %s.' % ( + name, type, book.name)) + + return Symbol(book, name, type, link, deprecated, since) + + def __init__(self, book, name, type, link=None, deprecated=None, since=None): + self.__book = book + self.__name = name + self.__type = type + self.__link = link + self.__deprecated = deprecated + self.__since = since + self.__matches = [] + + def __repr__(self): + return ( + '' % ( + self.name, self.type, self.since, self.deprecated)) + + + book = property(lambda self: self.__book) + name = property(lambda self: self.__name) + type = property(lambda self: self.__type) + link = property(lambda self: self.__link) + deprecated = property(lambda self: self.__deprecated) + matches = property(lambda self: self.__matches) + since = property(lambda self: self.__since) + +def parse_cmdline(): + options = OptionParser(version="@VERSION@") + + options.add_option('-b', '--book', dest='books', + help='name of a devhelp book to consider', + default=[], action='append') + options.add_option('-d', '--html-dir', metavar='PATH', dest='dirs', + help='path of additional folders with devhelp books', + default=[], action='append') + options.add_option('-s', '--summarize', action='store_true', default=False, + help='print only a brief summary', dest='summarize') + options.add_option('-u', '--list-unknown', action='store_true', default=False, + help='list symbols not found in any book', dest='unknown') + options.add_option('-v', '--verbose', action='store_true', default=False, + help='print additional information') + + return options.parse_args() + +def merge_gnome_path(options): + path = environ.get('GNOME2_PATH') + path = path and path.split(':') or [] + + prefix = popen( + '@PKG_CONFIG@ --variable=prefix glib-2.0' + ).readline().rstrip() + + path.insert(0, prefix) + path = filter(None, [p.strip() for p in path]) + + path = [[ + os.path.join(p, 'share', 'devhelp', 'books'), + os.path.join(p, 'share', 'gtk-doc', 'html')] + for p in path] + + path = reduce(list.__add__, path) + path = filter(os.path.isdir, path) + + options.dirs += path + +def summarize_matches(matches): + counts = {} + for filename, lineno, symbol in matches: + if not isinstance(symbol, Symbol): + if options.verbose: + print('%s:%d: unknown symbol %s' % (filename, lineno, symbol)) + continue + + since = '%s-%s' % (symbol.book.name, symbol.since) + name = symbol.name + if since not in counts: + counts[since] = {} + counts[since][name] = counts[since].get(name, 0) + 1 + + for since, stats in counts.items(): + counts[since] = list(sorted(stats.items(), key=lambda x: -x[1])) + + return counts + +if '__main__' == __name__: + options, args = parse_cmdline() + + merge_gnome_path(options) + + if not options.books: + options.books = default_books + + def trace(message, *args): + if options.verbose: print(message % args) + + def parse_book(name): + try: + match = re.match(r'^(.*?)(?::(\d+(?:\.\d+)*))?$', name) + name, version = match.groups() + trace('reading book: %s', name) + + version = version and Symbol.VersionInfo(version) + return name, Book(name, options.dirs, version) + + except IOError as e: + print >>stderr, 'WARNING: %s.' % e + + def scan_source_file(name): + contents = None + + try: + contents = __comment_regex.sub('', file(name).read()) + + except IOError as e: + print >>stderr, e + + if contents: + trace('scanning: %s', name) + lines = contents.split('\n') + + for lineno in range(len(lines)): + for word in __word_regex.findall(lines[lineno]): + symbol = symbols.get(word) + + if symbol: + symbol.matches.append((name, lineno, symbol)) + + elif options.unknown and word.find('_') > 0: + unknown_symbols.append((name, lineno, word)) + + unknown_symbols = [] + matches, symbols = dict(), dict() + books = dict(filter(None, map(parse_book, set(options.books)))) + + for book in books.values(): + symbols.update(book.symbols) + + for name in args: + if os.path.isdir(name): + for path, dirs, files in walk(name): + for f in files: + if f.endswith('.c'): + scan_source_file(os.path.join(path, f)) + + else: + scan_source_file(name) + + matches = [] + + for book in books.values(): + requirements = book.find_requirements().items() + requirements.sort() + + if requirements: + for symbol in requirements[-1][1]: + matches += symbol.matches + + if options.unknown: + matches += unknown_symbols + + matches.sort() + + if options.summarize: + summary = summarize_matches(matches) + for since in sorted(summary.keys()): + print('%s required for' % since) + for x in summary[since]: + print(' %u %s' % (x[1], x[0])) + else: + for filename, lineno, symbol in matches: + if isinstance(symbol, Symbol): + args = filename, lineno, symbol.book.name, symbol.since, symbol.name + print('%s:%d: %s-%s required for %s' % args) + + elif options.verbose: + print('%s:%d: unknown symbol %s' % (filename, lineno, symbol)) + + if options.unknown: + unknown = [m[2].split('_')[0].lower() for m in unknown_symbols] + unknown = list(set(unknown)) + unknown.sort() + + print('unknown prefixes: %s' % ', '.join(unknown)) + + raise SystemExit(matches and 1 or 0) diff --git a/gtk-doc-for-gtk4/gtkdoc-fixxref.in b/gtk-doc-for-gtk4/gtkdoc-fixxref.in new file mode 100755 index 0000000000..3183fd2a0f --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-fixxref.in @@ -0,0 +1,61 @@ +#!@PYTHON@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import os +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, fixxref + + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-fixxref version %s - fix cross references in html files' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--module', required=True, + help='Name of the doc module being processed.') + parser.add_argument('--module-dir', default='', + help='The directory which contains the generated HTML.') + parser.add_argument('--html-dir', default='', + help='The directory where gtk-doc generated documentation is' + 'installed.') + parser.add_argument('--extra-dir', default=[], action='append', + help='Directories to recursively scan for indices (*.devhelp2)' + 'in addition to HTML_DIR') + parser.add_argument('--src-lang', default='c', + help='Programing language used for syntax highlighting. The' + 'available languages depend on the source' + 'highlighter you use.') + + options = parser.parse_args() + + if not options.module_dir: + options.module_dir = os.path.join(options.html_dir, options.module) + + common.setup_logging() + + fixxref.Run(options) diff --git a/gtk-doc-for-gtk4/gtkdoc-mkdb.in b/gtk-doc-for-gtk4/gtkdoc-mkdb.in new file mode 100755 index 0000000000..641f3c4979 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-mkdb.in @@ -0,0 +1,65 @@ +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +from __future__ import print_function + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, mkdb + +if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--module', required=True, + help='Name of the doc module being parsed') + parser.add_argument('--source-dir', action='append', dest='source_dir', default=[]) + parser.add_argument('--source-suffixes', dest='source_suffixes', default='') + parser.add_argument('--ignore-files', dest='ignore_files', default='') + parser.add_argument('--output-dir', dest='output_dir', default='') + parser.add_argument('--tmpl-dir', dest='tmpl_dir', help="DEPRECATED") + parser.add_argument('--main-sgml-file', dest='main_sgml_file', default='') + parser.add_argument('--expand-content-files', dest='expand_content_files', default='') + group = parser.add_mutually_exclusive_group() + group.add_argument('--sgml-mode', action='store_true', default=False, dest='sgml_mode') + group.add_argument('--xml-mode', action='store_true', default=False, dest='xml_mode') + parser.add_argument('--default-stability', dest='default_stability', + choices=['', 'Stable', 'Private', 'Unstable'], default='') + parser.add_argument('--default-includes', dest='default_includes', default='') + parser.add_argument('--output-format', default='xml') # MUST be 'xml', deprecate? + parser.add_argument('--name-space', dest='name_space', default='') + parser.add_argument('--outputallsymbols', default=False, action='store_true') + parser.add_argument('--outputsymbolswithoutsince', default=False, action='store_true') + + options = parser.parse_args() + + if options.output_format != "xml": + sys.exit('Invalid format "%s" passed to --output.format' % options.output_format) + + common.setup_logging() + + mkdb.Run(options) diff --git a/gtk-doc-for-gtk4/gtkdoc-mkhtml.in b/gtk-doc-for-gtk4/gtkdoc-mkhtml.in new file mode 100755 index 0000000000..b09f7a9f51 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-mkhtml.in @@ -0,0 +1,55 @@ +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Owen Taylor +# 2001-2005 Damon Chaplin +# 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, mkhtml + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-mkhtml version %s - generate documentation in html format' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--verbose', default=False, action='store_true', + help='Print extra output while processing') + parser.add_argument('--path', default=[], action='append', + help='Extra source directories') + parser.add_argument('args', nargs='*', + help='MODULE DRIVER_FILE') + # TODO: only for testing, replace with env-var + parser.add_argument('--uninstalled', action='store_true', default=False, + help='???') + + options = parser.parse_args() + if len(options.args) < 2: + sys.exit('Too few arguments') + + common.setup_logging() + + sys.exit(mkhtml.run(options)) diff --git a/gtk-doc-for-gtk4/gtkdoc-mkhtml2.in b/gtk-doc-for-gtk4/gtkdoc-mkhtml2.in new file mode 100755 index 0000000000..fef2962da9 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-mkhtml2.in @@ -0,0 +1,58 @@ +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2018 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, mkhtml2 + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-mkhtml version %s - generate documentation in html format' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--output-dir', default='.', + help='The directory where the results are stored') + parser.add_argument('--path', default=[], action='append', + help='Extra source directories') + parser.add_argument('--extra-dir', default=[], action='append', + help='Directories to recursively scan for indices (*.devhelp2)' + 'in addition to HTML_DIR') + parser.add_argument('--src-lang', default='c', + help='Programing language used for syntax highlighting. This' + 'can be any language pygments supports.') + parser.add_argument('args', nargs='*', + help='MODULE DRIVER_FILE') + # TODO: only for testing, replace with env-var + parser.add_argument('--uninstalled', action='store_true', default=False, + help='???') + + options = parser.parse_args() + if len(options.args) != 2: + sys.exit('Too few arguments') + + common.setup_logging() + + sys.exit(mkhtml2.run(options)) diff --git a/gtk-doc-for-gtk4/gtkdoc-mkman.in b/gtk-doc-for-gtk4/gtkdoc-mkman.in new file mode 100755 index 0000000000..8f7b018a70 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-mkman.in @@ -0,0 +1,53 @@ +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Owen Taylor +# 2001-2005 Damon Chaplin +# 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, mkman + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-mkman version %s - generate documentation in man format' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--verbose', default=False, action='store_true', + help='Print extra output while processing') + parser.add_argument('--path', default=[], action='append', + help='Extra source directories') + parser.add_argument('args', nargs=2, + help='MODULE DRIVER_FILE') + # TODO: only for testing, replace with env-var + parser.add_argument('--uninstalled', action='store_true', default=False, + help='???') + + options = parser.parse_args() + + common.setup_logging() + + sys.exit(mkman.run(options)) diff --git a/gtk-doc-for-gtk4/gtkdoc-mkpdf.in b/gtk-doc-for-gtk4/gtkdoc-mkpdf.in new file mode 100755 index 0000000000..7dca4b067b --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-mkpdf.in @@ -0,0 +1,52 @@ +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, mkpdf + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-mkpdf version %s - generate documentation in pdf format' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--verbose', default=False, action='store_true', + help='Print extra output while processing.') + parser.add_argument('--path', default=[], action='append', + help='Extra source directories.') + parser.add_argument('--imgdir', default=[], action='append', + help='Extra image directories.') + parser.add_argument('--uninstalled', action='store_true', default=False, + help='???') + parser.add_argument('args', nargs=2, + help='MODULE DRIVER_FILE') + + options = parser.parse_args() + + common.setup_logging() + + sys.exit(mkpdf.run(options)) diff --git a/gtk-doc-for-gtk4/gtkdoc-rebase.in b/gtk-doc-for-gtk4/gtkdoc-rebase.in new file mode 100755 index 0000000000..e8b0bf5038 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-rebase.in @@ -0,0 +1,60 @@ +#!@PYTHON@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007 David Necas (Yeti) +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, rebase + + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-rebase version %s - rewrite links in html docs' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--html-dir', required=True, + help='The directory which contains the installed HTML') + parser.add_argument('--other-dir', default=[], action='append', + help='Directories to recursively scan for indices (*.devhelp2).' + 'May be used more than once for multiple directories.') + parser.add_argument('--dest-dir', default='', + help='Staging area virtual root, this prefix will be removed' + 'from HTML_DIR for relative link calculation.') + parser.add_argument('--aggressive', action='store_true', default=False, + help='Rebase links to all files that are under a directory matching a package name.') + parser.add_argument('--verbose', action='store_true', default=False, + help='Print extra output while processing') + parser.add_argument('--online', action='store_true', default=False, + help='Prefer cross-references to online documents') + parser.add_argument('--relative', action='store_true', default=False, + help='Prefer relative cross-references') + + options = parser.parse_args() + + common.setup_logging() + + sys.exit(rebase.run(options)) diff --git a/gtk-doc-for-gtk4/gtkdoc-scan.in b/gtk-doc-for-gtk4/gtkdoc-scan.in new file mode 100755 index 0000000000..7893ebc156 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-scan.in @@ -0,0 +1,63 @@ +#!@PYTHON@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +from __future__ import print_function + +import argparse +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, scan + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-scan version %s - scan header files for public symbols' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--module', required=True, + help='Name of the doc module being processed.') + parser.add_argument('--source-dir', action='append', default=[], + help='Directories containing the source files to scan') + parser.add_argument('--ignore-headers', default='', + help='A space-separated list of header files/dirs not to scan') + parser.add_argument('--output-dir', default='.', + help='The directory where the results are stored') + parser.add_argument('--deprecated-guards', default='does_not_match_any_cpp_symbols_at_all_nope', + help='A |-separated list of symbols used as deprecation guards') + parser.add_argument('--ignore-decorators', default='(?=no)match', + help='A |-separated list of additional decorators in' + 'declarations that should be ignored') + parser.add_argument('--rebuild-sections', action='store_true', default=False, + help='Rebuild (overwrite) the MODULE-sections.txt file') + parser.add_argument('--rebuild-types', action='store_true', default=False, + help='Automatically recreate the MODULE.types file using' + 'all the *_get_type() functions found') + parser.add_argument('headers', nargs='*') + + options = parser.parse_args() + + common.setup_logging() + + scan.Run(options) diff --git a/gtk-doc-for-gtk4/gtkdoc-scangobj.in b/gtk-doc-for-gtk4/gtkdoc-scangobj.in new file mode 100755 index 0000000000..7660c70b5b --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc-scangobj.in @@ -0,0 +1,81 @@ +#!@PYTHON@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import argparse +import os +import sys + +try: + import gtkdoc_uninstalled +except ModuleNotFoundError: + sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, scangobj + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-rebase version %s - introspect g-objects' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--module', required=True, + help='Name of the doc module being parsed') + parser.add_argument('--types', default='', + help='The name of the file to store the types in') + parser.add_argument('--type-init-func', default='', + help='The init function(s) to call instead of g_type_init()') + parser.add_argument('--query-child-properties', default='', + help='A function that returns a list of child properties for a class') + parser.add_argument('--output-dir', default='.', + help='The directory where the results are stored') + parser.add_argument('--cc', default='', help='The compiler to use') + parser.add_argument('--ld', default='', help='The linker to use') + parser.add_argument('--cflags', type=str, default=[], help='Compiler flags', + action='append') + parser.add_argument('--ldflags', type=str, default=[], help='Linker flags', + action='append') + parser.add_argument('--run', default='', + help='Command for running the scanner') + parser.add_argument('--verbose', action='store_true', default=False, + help='Print extra output while processing') + + options = parser.parse_args() + + if options.types == '': + options.types = os.path.join(options.output_dir, options.module + '.types') + if options.cflags: + options.cflags = ' '.join(options.cflags) + if options.ldflags: + options.ldflags = ' '.join(options.ldflags) + + if not options.cc: + options.cc = os.environ.get('CC', 'gcc') + if not options.ld: + options.ld = os.environ.get('LD', options.cc) + if not options.cflags: + options.cflags = os.environ.get('CFLAGS', '') + if not options.ldflags: + options.ldflags = os.environ.get('LDFLAGS', '') + if not options.run: + options.run = os.environ.get('RUN', '') + + common.setup_logging() + + sys.exit(scangobj.run(options)) diff --git a/gtk-doc-for-gtk4/gtkdoc/__init__.py b/gtk-doc-for-gtk4/gtkdoc/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/gtk-doc-for-gtk4/gtkdoc/check.py b/gtk-doc-for-gtk4/gtkdoc/check.py new file mode 100755 index 0000000000..c2815ac9c3 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/check.py @@ -0,0 +1,150 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2007 David Nečas +# 2007-2017 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +The check tool runs various tests on built documentation and outputs test +results. Can be run druring make check, by adding this to the documentations +Makefile.am: TESTS = $(GTKDOC_CHECK). +""" + +import os +import re +from glob import glob + + +class FileFormatError(Exception): + pass + + +def grep(regexp, lines, what): + pattern = re.compile(regexp) + for line in lines: + for match in re.finditer(pattern, line): + return match.group(1) + raise FileFormatError(what) + + +def check_empty(filename): + with open(filename, "rb") as f: + count = sum(1 for line in f if line.strip()) + return count + + +def read_file(filename): + with open(filename, 'r', encoding='utf-8') as f: + return f.read().splitlines() + + +def check_includes(filename): + # Check that each XML file in the xml directory is included in doc_main_file + lines = read_file(filename) + num_missing = 0 + for include in glob('xml/*.xml'): + try: + next(line for line in lines if include in line) + except StopIteration: + num_missing += 1 + print('%s:1:E: doesn\'t appear to include "%s"' % (filename, include)) + + return num_missing + + +def get_variable(env, lines, variable): + value = env.get(variable, None) + if value is None: + value = grep(r'^\s*' + variable + r'\s*=\s*(\S+)', lines, variable) + return value + + +def run_tests(workdir, doc_module, doc_main_file): + checks = 4 + + print('Running suite(s): gtk-doc-' + doc_module) + + # Test #1 + statusfilename = os.path.join(workdir, doc_module + '-undocumented.txt') + statusfile = read_file(statusfilename) + try: + undocumented = int(grep(r'^(\d+)\s+not\s+documented\.\s*$', + statusfile, 'number of undocumented symbols')) + incomplete = int(grep(r'^(\d+)\s+symbols?\s+incomplete\.\s*$', + statusfile, 'number of incomplete symbols')) + except FileFormatError as e: + print('Cannot find %s in %s' % (str(e), statusfilename)) + return checks # consider all failed + + total = undocumented + incomplete + if total: + print(doc_module + '-undocumented.txt:1:E: %d undocumented or incomplete symbols' % total) + + # Test #2 + undeclared = check_empty(os.path.join(workdir, doc_module + '-undeclared.txt')) + if undeclared: + print(doc_module + '-undeclared.txt:1:E: %d undeclared symbols\n' % undeclared) + + # Test #3 + unused = check_empty(os.path.join(workdir, doc_module + '-unused.txt')) + if unused: + print(doc_module + '-unused.txt:1:E: %d unused documentation entries\n' % unused) + + # Test #4 + missing_includes = check_includes(os.path.join(workdir, doc_main_file)) + + # Test Summary + failed = (total > 0) + (undeclared != 0) + (unused != 0) + (missing_includes != 0) + rate = 100.0 * (checks - failed) / checks + print("%.1f%%: Checks %d, Failures: %d" % (rate, checks, failed)) + return failed + + +def run(options=None): + """Runs the tests. + + Returns: + int: a system exit code. + """ + + # Get parameters from test env, if not there try to grab them from the makefile + # We like Makefile.am more but builddir does not necessarily contain one. + makefilename = 'Makefile.am' + if not os.path.exists(makefilename): + makefilename = 'Makefile' + makefile = [] + try: + makefile = read_file(makefilename) + except (OSError, IOError): + pass + + # For historic reasons tests are launched in srcdir + workdir = os.environ.get('BUILDDIR', None) + if not workdir: + workdir = '.' + + try: + doc_module = get_variable(os.environ, makefile, 'DOC_MODULE') + doc_main_file = get_variable(os.environ, makefile, 'DOC_MAIN_SGML_FILE') + except FileFormatError as e: + print('Cannot find %s in %s' % (str(e), makefilename)) + return 1 + + doc_main_file = doc_main_file.replace('$(DOC_MODULE)', doc_module) + + return run_tests(workdir, doc_module, doc_main_file) diff --git a/gtk-doc-for-gtk4/gtkdoc/common.py b/gtk-doc-for-gtk4/gtkdoc/common.py new file mode 100644 index 0000000000..82e051be8e --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/common.py @@ -0,0 +1,582 @@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2001 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +from collections import OrderedDict +import logging +import os +import re +import subprocess +import sys + +from . import config + + +def setup_logging(): + """Check GTKDOC_TRACE environment variable. + + Set python log level to the value of the environment variable (DEBUG, INFO, + WARNING, ERROR and CRITICAL) or INFO if the environment variable is empty. + """ + log_level = os.environ.get('GTKDOC_TRACE', 'WARNING') + if log_level == '': + log_level = 'WARNING' + logging.basicConfig(stream=sys.stdout, + level=logging.getLevelName(log_level.upper()), + format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s') + # When redirecting the output and running with a non utf-8 locale + # we get UnicodeEncodeError: + encoding = sys.stdout.encoding + if 'PYTHONIOENCODING' not in os.environ and (not encoding or encoding != 'UTF-8'): + sys.stdout.flush() + sys.stdout = open(sys.stdout.fileno(), mode='w', encoding='utf8', buffering=1) + + +def UpdateFileIfChanged(old_file, new_file, make_backup): + """Compares the old version of the file with the new version and if the + file has changed it moves the new version into the old versions place. This + is used so we only change files if needed, so we can do proper dependency + tracking. + + Args: + old_file (str): The pathname of the old file. + new_file (str): The pathname of the new version of the file. + make_backup (bool): True if a backup of the old file should be kept. + It will have the .bak suffix added to the file name. + + Returns: + bool: It returns False if the file hasn't changed, and True if it has. + """ + + logging.debug("Comparing %s with %s...", old_file, new_file) + + if os.path.exists(old_file): + old_contents = new_contents = None + with open(old_file, 'rb') as f: + old_contents = f.read() + with open(new_file, 'rb') as f: + new_contents = f.read() + if old_contents == new_contents: + os.unlink(new_file) + logging.debug("-> content is the same.") + return False + + if make_backup: + backupname = old_file + '.bak' + if os.path.exists(backupname): + os.unlink(backupname) + os.rename(old_file, backupname) + else: + os.unlink(old_file) + logging.debug("-> content differs.") + else: + logging.debug("-> %s created.", old_file) + + os.rename(new_file, old_file) + return True + + +def GetModuleDocDir(module_name): + """Get the docdir for the given module via pkg-config + + Args: + module_name (string): The module, e.g. 'glib-2.0' + + Returns: + str: the doc directory or None + """ + path = None + try: + path = subprocess.check_output([config.pkg_config, '--variable=prefix', module_name], universal_newlines=True) + except subprocess.CalledProcessError: + return None + return os.path.join(path.strip(), 'share/gtk-doc/html') + + +def LogWarning(filename, line, message): + """Log a warning in gcc style format + + Args: + file (str): The file the error comes from + line (int): line number in the file + message (str): the error message to print + """ + filename = filename or "unknown" + + # TODO: write to stderr + print("%s:%d: warning: %s" % (filename, line, message)) + + +def CreateValidSGMLID(xml_id): + """Creates a valid SGML 'id' from the given string. + + According to http://www.w3.org/TR/html4/types.html#type-id "ID and NAME + tokens must begin with a letter ([A-Za-z]) and may be followed by any number + of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), + and periods (".")." + + When creating SGML IDS, we append ":CAPS" to all all-caps identifiers to + prevent name clashes (SGML ids are case-insensitive). (It basically never is + the case that mixed-case identifiers would collide.) + + Args: + id (str): The text to be converted into a valid SGML id. + + Returns: + str: The converted id. + """ + + # Special case, '_' would end up as '' so we use 'gettext-macro' instead. + if xml_id == '_': + return "gettext-macro" + + xml_id = re.sub(r'[,;]', '', xml_id) + xml_id = re.sub(r'[_ ]', '-', xml_id) + xml_id = re.sub(r'^-+', '', xml_id) + xml_id = xml_id.replace('::', '-') + xml_id = xml_id.replace(':', '--') + + # Append ":CAPS" to all all-caps identifiers + # FIXME: there are some inconsistencies here, we have index files containing e.g. TRUE--CAPS + if xml_id.isupper() and not xml_id.endswith('-CAPS'): + xml_id += ':CAPS' + + return xml_id + + +# Parsing helpers (move to mkdb ?) + +class ParseError(Exception): + pass + + +def PreprocessStructOrEnum(declaration): + """Trim a type declaration for display. + + Removes private sections and comments from the declaration. + + Args: + declaration (str): the type declaration (struct or enum) + + Returns: + str: the trimmed declaration + """ + # Remove private symbols + # Assume end of declaration if line begins with '}' + declaration = re.sub(r'\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))', + '', declaration, flags=re.MULTILINE | re.DOTALL) + + # Remove all other comments + declaration = re.sub(r'\n\s*/\*.*?\*/\s*\n', r'\n', declaration, flags=re.MULTILINE | re.DOTALL) + declaration = re.sub(r'/\*([^*]+|\*(?!/))*\*/', r' ', declaration) + declaration = re.sub(r'\n\s*//.*?\n', r'\n', declaration, flags=re.MULTILINE | re.DOTALL) + declaration = re.sub(r'//.*', '', declaration) + + return declaration + + +# TODO: output_function_params is always passed as 0 +# TODO: we always pass both functions +def ParseStructDeclaration(declaration, is_object, output_function_params, typefunc=None, namefunc=None): + """ Parse a struct declaration. + + Takes a structure declaration and breaks it into individual type declarations. + + Args: + declaration (str): the declaration to parse + is_object (bool): true if this is an object structure + output_function_params (bool): true if full type is wanted for function pointer members + typefunc (func): function to apply to type + namefunc (func): function to apply to name + + Returns: + dict: map of (symbol, decl) pairs describing the public declaration + """ + + # For forward struct declarations just return an empty array. + if re.search(r'(?:struct|union)\s+\S+\s*;', declaration, flags=re.MULTILINE | re.DOTALL): + return {} + + # Remove all private parts of the declaration + # For objects, assume private + if is_object: + declaration = re.sub(r'''((?:struct|union)\s+\w*\s*\{) + .*? + (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))''', + r'\1', declaration, flags=re.MULTILINE | re.DOTALL | re.VERBOSE) + + # Remove g_iface, parent_instance and parent_class if they are first member + declaration = re.sub(r'(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;', r'\1', declaration) + + declaration = PreprocessStructOrEnum(declaration) + + if declaration.strip() == '': + return {} + + # Prime match after "struct/union {" declaration + match = re.search(r'(?:struct|union)\s+\w*\s*\{', declaration, flags=re.MULTILINE | re.DOTALL) + if not match: + raise ParseError('Declaration "%s" does not begin with "struct/union [NAME] {"' % declaration) + + logging.debug('public fields in struct/union: %s', declaration) + + result = OrderedDict() + + # Treat lines in sequence, allowing singly nested anonymous structs and unions. + for m in re.finditer(r'\s*([^{;]+(\{[^\}]*\}[^{;]+)?);', declaration[match.end():], flags=re.MULTILINE | re.DOTALL): + line = m.group(1) + + logging.debug('checking "%s"', line) + + if re.search(r'^\s*\}\s*\w*\s*$', line): + break + + # FIXME: Just ignore nested structs and unions for now + if '{' in line: + continue + + # ignore preprocessor directives + line = re.sub(r'^#.*?\n\s*', '', line, flags=re.MULTILINE | re.DOTALL) + + if re.search(r'^\s*\}\s*\w*\s*$', line): + break + + func_match = re.search(r'''^ + (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)? # mod1 + (\w+)\s* # type + (\**(?:\s*restrict)?)\s* # ptr1 + (const\s+)? # mod2 + (\**\s*) # ptr2 + (const\s+)? # mod3 + \(\s*\*\s*(\w+)\s*\)\s* # name + \(([^)]*)\)\s* # func_params + $''', line, flags=re.VERBOSE) + vars_match = re.search(r'''^ + ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1 + (\w+)\s* # type + (\** \s* const\s+)? # mod2 + (.*) # variables + $''', line, flags=re.VERBOSE) + + # Try to match structure members which are functions + if func_match: + mod1 = func_match.group(1) or '' + if func_match.group(2): + mod1 += func_match.group(2) + func_type = func_match.group(3) + ptr1 = func_match.group(4) + mod2 = func_match.group(5) or '' + ptr2 = func_match.group(6) + mod3 = func_match.group(7) or '' + name = func_match.group(8) + func_params = func_match.group(9) + ptype = func_type + if typefunc: + ptype = typefunc(func_type, '%s' % func_type) + pname = name + if namefunc: + pname = namefunc(name) + + if output_function_params: + result[name] = '%s%s%s%s%s%s (*%s) (%s)' % ( + mod1, ptype, ptr1, mod2, ptr2, mod3, pname, func_params) + else: + result[name] = '%s ()' % pname + + # Try to match normal struct fields of comma-separated variables/ + elif vars_match: + mod1 = vars_match.group(1) or '' + if vars_match.group(2): + mod1 += vars_match.group(2) + vtype = vars_match.group(3) + ptype = vtype + if typefunc: + ptype = typefunc(vtype, '%s' % vtype) + mod2 = vars_match.group(4) or '' + if mod2: + mod2 = ' ' + mod2 + var_list = vars_match.group(5) + + logging.debug('"%s" "%s" "%s" "%s"', mod1, vtype, mod2, var_list) + + mod1 = mod1.replace(' ', ' ') + mod2 = mod2.replace(' ', ' ') + + for n in var_list.split(','): + # Each variable can have any number of '*' before the identifier, + # and be followed by any number of pairs of brackets or a bit field specifier. + # e.g. *foo, ***bar, *baz[12][23], foo : 25. + m = re.search( + r'^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $', + n, flags=re.VERBOSE) + if m: + ptrs = m.group(1) + name = m.group(2) + array = m.group(3) or '' + bits = m.group(4) + if bits: + bits = ' ' + bits + else: + bits = '' + if ptrs and not ptrs.endswith('*'): + ptrs += ' ' + + array = array.replace(' ', ' ') + bits = bits.replace(' ', ' ') + + pname = name + if namefunc: + pname = namefunc(name) + + result[name] = '%s%s%s %s%s%s%s;' % (mod1, ptype, mod2, ptrs, pname, array, bits) + + logging.debug('Matched line: %s%s%s %s%s%s%s', mod1, ptype, mod2, ptrs, pname, array, bits) + else: + logging.warning('Cannot parse struct field: "%s"', n) + + else: + logging.warning('Cannot parse structure field: "%s"', line) + + return result + + +def ParseEnumDeclaration(declaration): + """Parse an enum declaration. + + This function takes a enumeration declaration and breaks it into individual + enum member declarations. + + Args: + declaration (str): the declaration to parse + + Returns: + str: list of strings describing the public declaration + """ + + # For forward struct declarations just return an empty array. + if re.search(r'enum\s+\S+\s*;', declaration, flags=re.MULTILINE | re.DOTALL): + return () + + declaration = PreprocessStructOrEnum(declaration) + + if declaration.strip() == '': + return () + + result = [] + + # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3)) + # to avoid getting confused by commas they might contain. This doesn't + # handle nested parentheses correctly. + declaration = re.sub(r'\([^)\n]+\)', '', declaration) + + # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting + # confused with end of enumeration. + # See https://bugzilla.gnome.org/show_bug.cgi?id=741305 + declaration = re.sub(r'\'.\'', '', declaration) + + # Remove comma from comma - possible whitespace - closing brace sequence + # since it is legal in GNU C and C99 to have a trailing comma but doesn't + # result in an actual enum member + declaration = re.sub(r',(\s*})', r'\1', declaration) + + # Prime match after "typedef enum {" declaration + match = re.search(r'(typedef\s+)?enum\s*(\S+\s*)?\{', declaration, flags=re.MULTILINE | re.DOTALL) + if not match: + raise ParseError('Enum declaration "%s" does not begin with "typedef enum {" or "enum [NAME] {"' % declaration) + + logging.debug("public fields in enum: %s'", declaration) + + # Treat lines in sequence. + for m in re.finditer(r'\s*([^,\}]+)([,\}])', declaration[match.end():], flags=re.MULTILINE | re.DOTALL): + line = m.group(1) + terminator = m.group(2) + + # ignore preprocessor directives + line = re.sub(r'^#.*?\n\s*', '', line, flags=re.MULTILINE | re.DOTALL) + + m1 = re.search(r'^(\w+)\s*(=.*)?$', line, flags=re.MULTILINE | re.DOTALL) + # Special case for GIOCondition, where the values are specified by + # macros which expand to include the equal sign like '=1'. + m2 = re.search(r'^(\w+)\s*GLIB_SYSDEF_POLL', line, flags=re.MULTILINE | re.DOTALL) + if m1: + result.append(m1.group(1)) + elif m2: + result.append(m2.group(1)) + elif line.strip().startswith('#'): + # Special case include of , just ignore it + # Special case for #ifdef/#else/#endif, just ignore it + break + else: + logging.warning('Cannot parse enumeration member: %s', line) + + if terminator == '}': + break + + return result + + +def ParseFunctionDeclaration(declaration, typefunc, namefunc): + """Parse a function declaration. + + This function takes a function declaration and breaks it into individual + parameter declarations. + + Args: + declaration (str): the declaration to parse + typefunc (func): function to apply to type + namefunc (func): function to apply to name + + Returns: + dict: map of (symbol, decl) pairs describing the prototype + """ + + result = OrderedDict() + + param_num = 0 + while declaration: + logging.debug('decl=[%s]', declaration) + + # skip whitespace and commas + declaration, n = re.subn(r'^[\s,]+', '', declaration) + if n: + continue + + declaration, n = re.subn(r'^void\s*[,\n]', '', declaration) + if n: + if param_num != 0: + logging.warning('void used as parameter %d in function %s', param_num, declaration) + result['void'] = namefunc('void') + param_num += 1 + continue + + declaration, n = re.subn(r'^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]', '', declaration) + if n: + result['...'] = namefunc('...') + param_num += 1 + continue + + # allow alphanumerics, '_', '[' & ']' in param names, try to match a standard parameter + # $1 $2 $3 $4 $5 + regex = r'^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]' + m = re.match(regex, declaration) + if m: + declaration = re.sub(regex, '', declaration) + + pre = m.group(1) or '' + type = m.group(2) + ptr = m.group(3) or '' + name = m.group(4) or '' + array = m.group(5) or '' + + pre = re.sub(r'\s+', ' ', pre) + type = re.sub(r'\s+', ' ', type) + ptr = re.sub(r'\s+', ' ', ptr) + ptr = re.sub(r'\s+$', '', ptr) + if ptr and not ptr.endswith('*'): + ptr += ' ' + + logging.debug('"%s" "%s" "%s" "%s" "%s"', pre, type, ptr, name, array) + + m = re.search(r'^((un)?signed .*)\s?', pre) + if name == '' and m: + name = type + type = m.group(1) + pre = '' + + if name == '': + name = 'Param' + str(param_num + 1) + + logging.debug('"%s" "%s" "%s" "%s" "%s"', pre, type, ptr, name, array) + + xref = typefunc(type, '%s' % type) + result[name] = namefunc('%s%s %s%s%s' % (pre, xref, ptr, name, array)) + param_num += 1 + continue + + # Try to match parameters which are functions + # $1 $2 $3 $4 $5 $6 $7 $8 + regex = r'^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]' + m = re.match(regex, declaration) + if m: + declaration = re.sub(regex, '', declaration) + + mod1 = m.group(1) or '' + if m.group(2): + mod1 += m.group(2) + type = m.group(3) + ptr1 = m.group(4) + mod2 = m.group(5) or '' + func_ptr = m.group(6) + name = m.group(7) + func_params = m.group(8) or '' + + if ptr1 and not ptr1.endswith('*'): + ptr1 += ' ' + func_ptr = re.sub(r'\s+', ' ', func_ptr) + + logging.debug('"%s" "%s" "%s" "%s" "%s"', mod1, type, mod2, func_ptr, name) + + xref = typefunc(type, '%s' % type) + result[name] = namefunc('%s%s%s%s (%s%s) (%s)' % (mod1, xref, ptr1, mod2, func_ptr, name, func_params)) + param_num += 1 + continue + + logging.warning('Cannot parse args for function in "%s"', declaration) + break + + return result + + +def ParseMacroDeclaration(declaration, namefunc): + """Parse a macro declaration. + + This function takes a macro declaration and breaks it into individual + parameter declarations. + + Args: + declaration (str): the declaration to parse + namefunc (func): function to apply to name + + Returns: + dict: map of (symbol, decl) pairs describing the macro + """ + + result = OrderedDict() + + logging.debug('decl=[%s]', declaration) + + m = re.search(r'^\s*#\s*define\s+\w+\(([^\)]*)\)', declaration) + if m: + params = m.group(1) + params = re.sub(r'\n', '', params) + + logging.debug('params=[%s]', params) + + for param in params.split(','): + param = param.strip() + + # Allow varargs variations + if param.endswith('...'): + param = '...' + + if param != '': + result[param] = namefunc(param) + + return result diff --git a/gtk-doc-for-gtk4/gtkdoc/config.py b/gtk-doc-for-gtk4/gtkdoc/config.py new file mode 100644 index 0000000000..b0a407ff6c --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/config.py @@ -0,0 +1,28 @@ +import os +import sys + +try: + from gtkdoc_uninstalled import builddir + exec(open(os.path.join(builddir, 'gtkdoc', 'config_data.py')).read()) +except ModuleNotFoundError: + from gtkdoc.config_data import * + + +def get_dirs(uninstalled): + try: + from gtkdoc_uninstalled import sourcedir + gtkdocdir = sourcedir + styledir = os.path.join(sourcedir, 'style') + except ModuleNotFoundError: + if uninstalled: + # this does not work from buiddir!=srcdir + gtkdocdir = os.path.split(sys.argv[0])[0] + if not os.path.exists(gtkdocdir + '/gtk-doc.xsl'): + # try 'srcdir' (set from makefiles) too + if os.path.exists(os.environ.get("ABS_TOP_SRCDIR", '') + '/gtk-doc.xsl'): + gtkdocdir = os.environ['ABS_TOP_SRCDIR'] + styledir = gtkdocdir + '/style' + else: + gtkdocdir = os.path.join(datadir, 'gtk-doc/data') + styledir = gtkdocdir + return (gtkdocdir, styledir) diff --git a/gtk-doc-for-gtk4/gtkdoc/config_data.py.in b/gtk-doc-for-gtk4/gtkdoc/config_data.py.in new file mode 100644 index 0000000000..1264374c06 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/config_data.py.in @@ -0,0 +1,14 @@ +version = "@VERSION@" + +# tools +dblatex = '@DBLATEX@' +fop = '@FOP@' +pkg_config = '@PKG_CONFIG@' +xsltproc = '@XSLTPROC@' + +# configured directories +prefix = '@prefix@' +datarootdir = "@datarootdir@".replace('${prefix}', prefix) +datadir = "@datadir@".replace('${datarootdir}', datarootdir) + +exeext = '@EXEEXT@' diff --git a/gtk-doc-for-gtk4/gtkdoc/fixxref.py b/gtk-doc-for-gtk4/gtkdoc/fixxref.py new file mode 100755 index 0000000000..356189cb1a --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/fixxref.py @@ -0,0 +1,405 @@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +''"Fix cross-references in the HTML documentation.''" + +import logging +import os +import re + +from . import common, highlight + +# This contains all the entities and their relative URLs. +Links = {} + +# failing link targets we don't warn about even once +NoLinks = { + 'char', + 'double', + 'float', + 'int', + 'long', + 'main', + 'signed', + 'unsigned', + 'va-list', + 'void', +} + + +def Run(options): + logging.info('options: %s', str(options.__dict__)) + + LoadIndicies(options.module_dir, options.html_dir, options.extra_dir) + ReadSections(options.module) + FixCrossReferences(options.module_dir, options.module, options.src_lang) + highlight.append_style_defs(os.path.join(options.module_dir, 'style.css')) + + +# TODO(ensonic): try to refactor so that we get a list of path's and then just +# loop over them. +# - module_dir is by default 'html' +# - html_dir can be set by configure, defaults to $(docdir) +def LoadIndicies(module_dir, html_dir, extra_dirs): + # Cache of dirs we already scanned for index files + dir_cache = {} + + path_prefix = '' + m = re.search(r'(.*?)/share/gtk-doc/html', html_dir) + if m: + path_prefix = m.group(1) + logging.info('Path prefix: %s', path_prefix) + prefix_match = r'^' + re.escape(path_prefix) + r'/' + + # We scan the directory containing GLib and any directories in GNOME2_PATH + # first, but these will be overridden by any later scans. + dir = common.GetModuleDocDir('glib-2.0') + if dir and os.path.exists(dir): + # Some predefined link targets to get links into type hierarchies as these + # have no targets. These are always absolute for now. + Links['GBoxed'] = dir + '/gobject/gobject-Boxed-Types.html' + Links['GEnum'] = dir + '/gobject/gobject-Enumeration-and-Flag-Types.html' + Links['GFlags'] = dir + '/gobject/gobject-Enumeration-and-Flag-Types.html' + Links['GInterface'] = dir + '/gobject/GTypeModule.html' + + if dir != html_dir: + logging.info('Scanning GLib directory: %s', dir) + ScanIndices(dir, (re.search(prefix_match, dir) is None), dir_cache) + else: + NoLinks.add('GBoxed') + NoLinks.add('GEnum') + NoLinks.add('GFlags') + NoLinks.add('GInterface') + + path = os.environ.get('GNOME2_PATH') + if path: + for dir in path.split(':'): + dir += 'share/gtk-doc/html' + if os.path.exists(dir) and dir != html_dir: + logging.info('Scanning GNOME2_PATH directory: %s', dir) + ScanIndices(dir, (re.search(prefix_match, dir) is None), dir_cache) + + logging.info('Scanning HTML_DIR directory: %s', html_dir) + ScanIndices(html_dir, False, dir_cache) + logging.info('Scanning MODULE_DIR directory: %s', module_dir) + ScanIndices(module_dir, False, dir_cache) + + # check all extra dirs, but skip already scanned dirs or subdirs of those + for dir in extra_dirs: + dir = dir.rstrip('/') + logging.info('Scanning EXTRA_DIR directory: %s', dir) + + # If the --extra-dir option is not relative and is not sharing the same + # prefix as the target directory of the docs, we need to use absolute + # directories for the links + if not dir.startswith('..') and re.search(prefix_match, dir) is None: + ScanIndices(dir, True, dir_cache) + else: + ScanIndices(dir, False, dir_cache) + + +def ScanIndices(scan_dir, use_absolute_links, dir_cache): + if not scan_dir or scan_dir in dir_cache: + return + dir_cache[scan_dir] = 1 + + logging.info('Scanning index directory: %s, absolute: %d', scan_dir, use_absolute_links) + + # TODO(ensonic): this code is the same as in rebase.py + if not os.path.isdir(scan_dir): + logging.info('Cannot open dir "%s"', scan_dir) + return + + subdirs = [] + for entry in sorted(os.listdir(scan_dir)): + full_entry = os.path.join(scan_dir, entry) + if os.path.isdir(full_entry): + subdirs.append(full_entry) + continue + + if entry.endswith('.devhelp2'): + # if devhelp-file is good don't read index.sgml + ReadDevhelp(full_entry, use_absolute_links) + elif entry == "index.sgml.gz" and not os.path.exists(os.path.join(scan_dir, 'index.sgml')): + # debian/ubuntu started to compress this as index.sgml.gz :/ + print(''' Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run: +gunzip %s +''' % full_entry) + elif entry.endswith('.devhelp2.gz') and not os.path.exists(full_entry[:-3]): + # debian/ubuntu started to compress this as *devhelp2.gz :/ + print('''Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run: +gunzip %s +''' % full_entry) + # we could consider supporting: gzip module + + # Now recursively scan the subdirectories. + for subdir in subdirs: + ScanIndices(subdir, use_absolute_links, dir_cache) + + +def ReadDevhelp(file, use_absolute_links): + # Determine the absolute directory, to be added to links in $file + # if we need to use an absolute link. + # $file will be something like /prefix/gnome/share/gtk-doc/html/gtk/$file + # We want the part up to 'html/.*' since the links in $file include + # the rest. + dir = "../" + if use_absolute_links: + # For uninstalled index files we'd need to map the path to where it + # will be installed to + if not file.startswith('./'): + m = re.search(r'(.*\/)(.*?)\/.*?\.devhelp2', file) + dir = m.group(1) + m.group(2) + '/' + else: + m = re.search(r'(.*\/)(.*?)\/.*?\.devhelp2', file) + if m: + dir += m.group(2) + '/' + else: + dir = '' + + logging.info('Scanning index file=%s, absolute=%d, dir=%s', file, use_absolute_links, dir) + + for line in open(file, 'r', encoding='utf-8'): + m = re.search(r' link="([^#]*)#([^"]*)"', line) + if m: + link = m.group(1) + '#' + m.group(2) + logging.debug('Found id: %s href: %s', m.group(2), link) + Links[m.group(2)] = dir + link + + +def ReadSections(module): + """We don't warn on missing links to non-public sysmbols.""" + for line in open(module + '-sections.txt', 'r', encoding='utf-8'): + m1 = re.search(r'^', line) + if line.startswith('#') or line.strip() == '': + continue + elif line.startswith('
'): + subsection = '' + elif m1: + subsection = m1.group(1) + elif line.startswith('') or line.startswith('
'): + continue + elif re.search(r'^(.*)<\/TITLE>', line): + continue + elif re.search(r'^<FILE>(.*)<\/FILE>', line): + continue + elif re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line): + continue + else: + symbol = line.strip() + if subsection == "Standard" or subsection == "Private": + NoLinks.add(common.CreateValidSGMLID(symbol)) + + +def FixCrossReferences(module_dir, module, src_lang): + # TODO(ensonic): use glob.glob()? + for entry in sorted(os.listdir(module_dir)): + full_entry = os.path.join(module_dir, entry) + if os.path.isdir(full_entry): + continue + elif entry.endswith('.html') or entry.endswith('.htm'): + FixHTMLFile(src_lang, module, full_entry) + + +def FixHTMLFile(src_lang, module, file): + logging.info('Fixing file: %s', file) + + content = open(file, 'r', encoding='utf-8').read() + + # FIXME: ideally we'd pass a clue about the example language to the highligher + # unfortunately the "language" attribute is not appearing in the html output + # we could patch the customization to have <code class="xxx"> inside of <pre> + def repl_func(m): + return HighlightSourcePygments(src_lang, m.group(1), m.group(2)) + content = re.sub( + r'<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>', + repl_func, content, flags=re.DOTALL) + content = re.sub(r'\<GTKDOCLINK\s+HREF=\"(.*?)\"\>(.*?)\</GTKDOCLINK\>', + r'\<GTKDOCLINK\ HREF=\"\1\"\>\2\</GTKDOCLINK\>', content, flags=re.DOTALL) + + # From the highlighter we get all the functions marked up. Now we can turn them into GTKDOCLINK items + def repl_func(m): + return MakeGtkDocLink(m.group(1), m.group(2), m.group(3)) + content = re.sub(r'(<span class=\"function\">)(.*?)(</span>)', repl_func, content, flags=re.DOTALL) + # We can also try the first item in stuff marked up as 'normal' + content = re.sub( + r'(<span class=\"normal\">\s*)(.+?)((\s+.+?)?\s*</span>)', repl_func, content, flags=re.DOTALL) + + lines = content.rstrip().split('\n') + + def repl_func_with_ix(i): + def repl_func(m): + return MakeXRef(module, file, i + 1, m.group(1), m.group(2)) + return repl_func + + for i in range(len(lines)): + lines[i] = re.sub(r'<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>', repl_func_with_ix(i), lines[i]) + if 'GTKDOCLINK' in lines[i]: + logging.info('make xref failed for line %d: "%s"', i, lines[i]) + + new_file = file + '.new' + content = '\n'.join(lines) + with open(new_file, 'w', encoding='utf-8') as h: + h.write(content) + + os.unlink(file) + os.rename(new_file, file) + + +def GetXRef(id): + href = Links.get(id) + if href: + return (id, href) + + # This is a workaround for some inconsistency we have with CreateValidSGMLID + if ':' in id: + tid = id.replace(':', '--') + href = Links.get(tid) + if href: + return (tid, href) + + # poor mans plural support + if id.endswith('es'): + tid = id[:-2] + href = Links.get(tid) + if href: + return (tid, href) + tid += '-struct' + href = Links.get(tid) + if href: + return (tid, href) + elif id.endswith('s'): + tid = id[:-1] + href = Links.get(tid) + if href: + return (tid, href) + tid += '-struct' + href = Links.get(tid) + if href: + return (tid, href) + + tid = id + '-struct' + href = Links.get(tid) + if href: + return (tid, href) + + return (id, None) + + +def ReportBadXRef(file, line, id, text): + logging.info('no link for: id=%s, linktext=%s', id, text) + + # don't warn multiple times and also skip blacklisted (ctypes) + if id in NoLinks: + return + # if it's a function, don't warn if it does not contain a "_" + # (transformed to "-") + # - gnome coding style would use '_' + # - will avoid wrong warnings for ansi c functions + if re.search(r' class=\"function\"', text) and '-' not in id: + return + # if it's a 'return value', don't warn (implicitly created link) + if re.search(r' class=\"returnvalue\"', text): + return + # if it's a 'type', don't warn if it starts with lowercase + # - gnome coding style would use CamelCase + if re.search(r' class=\"type\"', text) and id[0].islower(): + return + # don't warn for self links + if text == id: + return + + common.LogWarning(file, line, 'no link for: "%s" -> (%s).' % (id, text)) + NoLinks.add(id) + + +def MakeRelativeXRef(module, href): + # if it is a link to same module, remove path to make it work uninstalled + m = re.search(r'^\.\./' + module + '/(.*)$', href) + if m: + href = m.group(1) + return href + + +def MakeXRef(module, file, line, id, text): + href = GetXRef(id)[1] + + if href: + href = MakeRelativeXRef(module, href) + logging.info('Fixing link: %s, %s, %s', id, href, text) + return "<a href=\"%s\">%s</a>" % (href, text) + else: + ReportBadXRef(file, line, id, text) + return text + + +def MakeGtkDocLink(pre, symbol, post): + id = common.CreateValidSGMLID(symbol) + + # these are implicitly created links in highlighted sources + # we don't want warnings for those if the links cannot be resolved. + NoLinks.add(id) + + return pre + '<GTKDOCLINK HREF="' + id + '">' + symbol + '</GTKDOCLINK>' + post + + +def HighlightSourcePygments(src_lang, div_class, source): + # chop of leading and trailing empty lines, leave leading space in first real line + source = source.strip(' ') + source = source.strip('\n') + source = source.rstrip() + + # cut common indent + m = re.search(r'^(\s+)', source) + if m: + source = re.sub(r'^' + m.group(1), '', source, flags=re.MULTILINE) + # avoid double entity replacement + source = source.replace('<', '<') + source = source.replace('>', '>') + source = source.replace('&', '&') + + highlighted_source = highlight.highlight_code(source, src_lang) + if not highlighted_source: + highlighted_source = source + + # chop of leading and trailing empty lines + highlighted_source = highlighted_source.strip() + + # turn common urls in comments into links + highlighted_source = re.sub(r'<span class="url">(.*?)</span>', + r'<span class="url"><a href="\1">\1</a></span>', + highlighted_source, flags=re.DOTALL) + + # we do own line-numbering + line_count = highlighted_source.count('\n') + source_lines = '\n'.join([str(i) for i in range(1, line_count + 2)]) + + return """<div class="%s"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>%s</pre></td> + <td class="listing_code"><pre class="programlisting">%s</pre></td> + </tr> + </tbody> + </table> +</div> +""" % (div_class, source_lines, highlighted_source) diff --git a/gtk-doc-for-gtk4/gtkdoc/highlight.py b/gtk-doc-for-gtk4/gtkdoc/highlight.py new file mode 100644 index 0000000000..ba1c601b3d --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/highlight.py @@ -0,0 +1,51 @@ +#!/usr/bin/env python3 +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2018 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +Highlight sourcecode snippets. +""" +import os + +from pygments import highlight +from pygments.lexers import CLexer +from pygments.lexers import get_lexer_by_name +from pygments.formatters import HtmlFormatter + +# lazily constructed lexer cache +LEXERS = { + 'c': CLexer() +} +HTML_FORMATTER = HtmlFormatter(nowrap=True) + + +def highlight_code(code, lang='c'): + if lang not in LEXERS: + LEXERS[lang] = get_lexer_by_name(lang) + lexer = LEXERS.get(lang, None) + if not lexer: + return None + return highlight(code, lexer, HTML_FORMATTER) + + +def append_style_defs(css_file_name): + os.chmod(css_file_name, 0o644) + with open(css_file_name, 'at', newline='\n', encoding='utf-8') as css: + css.write(HTML_FORMATTER.get_style_defs()) diff --git a/gtk-doc-for-gtk4/gtkdoc/md_to_db.py b/gtk-doc-for-gtk4/gtkdoc/md_to_db.py new file mode 100644 index 0000000000..c8ff324395 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/md_to_db.py @@ -0,0 +1,758 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +Markdown to Docbook converter +""" + +import logging +import re + +# external functions +ExpandAbbreviations = MakeXRef = MakeHashXRef = tagify = None + +# Elements to consider non-block items in MarkDown parsing +MD_TEXT_LEVEL_ELEMENTS = { + 'emphasis', 'envar', 'filename', 'firstterm', 'footnote', 'function', 'literal', + 'manvolnum', 'option', 'replaceable', 'structfield', 'structname', 'title', + 'varname' +} +MD_ESCAPABLE_CHARS = r'\`*_{}[]()>#+-.!' +MD_GTK_ESCAPABLE_CHARS = r'@%' + + +def Init(): + # TODO(enonic): find a better way to do this + global ExpandAbbreviations, MakeXRef, MakeHashXRef, tagify + from .mkdb import ExpandAbbreviations, MakeXRef, MakeHashXRef, tagify + + +def MarkDownParseBlocks(lines, symbol, context): + md_blocks = [] + md_block = {"type": ''} + + logging.debug("parsing %s lines", len(lines)) + for line in lines: + logging.info("type='%s', int='%s', parsing '%s'", md_block["type"], md_block.get('interrupted'), line) + first_char = None + if line: + first_char = line[0] + + if md_block["type"] == "markup": + if 'closed' not in md_block: + if md_block["start"] in line: + md_block["depth"] += 1 + + if md_block["end"] in line: + if md_block["depth"] > 0: + md_block["depth"] -= 1 + else: + logging.info("closing tag '%s'", line) + md_block["closed"] = 1 + # TODO(ensonic): reparse inner text with MarkDownParseLines? + + md_block["text"] += "\n" + line + logging.info("add to markup: '%s'", line) + continue + + deindented_line = line.lstrip() + + if md_block["type"] == "heading": + # a heading is ended by any level less than or equal + if md_block["level"] == 1: + heading_match = re.search(r'^[#][ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line) + if re.search(r'^={4,}[ \t]*$', line): + text = md_block["lines"].pop() + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': text, + 'lines': [], + 'level': 1, + } + continue + elif heading_match: + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': heading_match.group(1), + 'lines': [], + 'level': 1, + } + if heading_match.group(2): + md_block['id'] = heading_match.group(2) + continue + else: + # push lines into the block until the end is reached + md_block["lines"].append(line) + continue + + else: + heading_match = re.search(r'^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line) + if re.search(r'^[=]{4,}[ \t]*$', line): + text = md_block["lines"].pop() + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': text, + 'lines': [], + 'level': 1, + } + continue + elif re.search(r'^[-]{4,}[ \t]*$', line): + text = md_block["lines"].pop() + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': text, + 'lines': [], + 'level': 2, + } + continue + elif heading_match: + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': heading_match.group(2), + 'lines': [], + 'level': len(heading_match.group(1)) + } + if heading_match.group(3): + md_block['id'] = heading_match.group(3) + continue + else: + # push lines into the block until the end is reached + md_block["lines"].append(line) + continue + elif md_block["type"] == "code": + end_of_code_match = re.search(r'^[ \t]*\]\|(.*)', line) + if end_of_code_match: + md_blocks.append(md_block) + md_block = {'type': "paragraph", + 'text': end_of_code_match.group(1), + 'lines': [], + } + else: + md_block["lines"].append(line) + continue + + if deindented_line == '': + logging.info('setting "interrupted" due to empty line') + md_block["interrupted"] = 1 + continue + + if md_block["type"] == "quote": + if 'interrupted' not in md_block: + line = re.sub(r'^[ ]*>[ ]?', '', line) + md_block["lines"].append(line) + continue + + elif md_block["type"] == "li": + marker = md_block["marker"] + marker_match = re.search(r'^([ ]{0,3})(%s)[ ](.*)' % marker, line) + if marker_match: + indentation = marker_match.group(1) + if md_block["indentation"] != indentation: + md_block["lines"].append(line) + else: + ordered = md_block["ordered"] + md_block.pop('last', None) + md_blocks.append(md_block) + md_block = {'type': "li", + 'ordered': ordered, + 'indentation': indentation, + 'marker': marker, + 'last': 1, + 'lines': [re.sub(r'^[ ]{0,4}', '', marker_match.group(3))], + } + continue + + if 'interrupted' in md_block: + if first_char == " ": + md_block["lines"].append('') + line = re.sub(r'^[ ]{0,4}', '', line) + md_block["lines"].append(line) + md_block.pop("interrupted", None) + continue + else: + line = re.sub(r'^[ ]{0,4}', '', line) + md_block["lines"].append(line) + continue + + # indentation sensitive types + heading_match = re.search(r'^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line) + code_match = re.search(r'^[ \t]*\|\[[ ]*(?:<!-- language="([^"]+?)" -->)?', line) + if heading_match: + # atx heading (#) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': heading_match.group(2), + 'lines': [], + 'level': len(heading_match.group(1)), + } + if heading_match.group(3): + md_block['id'] = heading_match.group(3) + continue + elif re.search(r'^={4,}[ \t]*$', line): + # setext heading (====) + + if md_block["type"] == "paragraph" and "interrupted" in md_block: + md_blocks.append(md_block.copy()) + md_block["type"] = "heading" + md_block["lines"] = [] + md_block["level"] = 1 + continue + elif re.search(r'^-{4,}[ \t]*$', line): + # setext heading (-----) + + if md_block["type"] == "paragraph" and "interrupted" in md_block: + md_blocks.append(md_block.copy()) + md_block["type"] = "heading" + md_block["lines"] = [] + md_block["level"] = 2 + + continue + elif code_match: + # code + md_block["interrupted"] = 1 + md_blocks.append(md_block) + md_block = {'type': "code", + 'lines': [], + } + if code_match.group(1): + md_block['language'] = code_match.group(1) + continue + + # indentation insensitive types + markup_match = re.search(r'^[ ]*<\??(\w+)[^>]*([\/\?])?[ \t]*>', line) + li_match = re.search(r'^([ ]*)[*+-][ ](.*)', line) + quote_match = re.search(r'^[ ]*>[ ]?(.*)', line) + if re.search(r'^[ ]*<!DOCTYPE/', line): + md_blocks.append(md_block) + md_block = {'type': "markup", + 'text': deindented_line, + 'start': '<', + 'end': '>', + 'depth': 0, + } + + elif markup_match: + # markup, including <?xml version="1.0"?> + tag = markup_match.group(1) + is_self_closing = markup_match.group(2) is not None + + # skip link markdown + # TODO(ensonic): consider adding more uri schemes (ftp, ...) + if re.search(r'https?', tag): + logging.info("skipping link '%s'", tag) + else: + # for TEXT_LEVEL_ELEMENTS, we want to keep them as-is in the paragraph + # instead of creation a markdown block. + scanning_for_end_of_text_level_tag = ( + md_block["type"] == "paragraph" and + 'start' in md_block and + 'closed' not in md_block) + logging.info("markup found '%s', scanning %s ?", tag, scanning_for_end_of_text_level_tag) + if tag not in MD_TEXT_LEVEL_ELEMENTS and not scanning_for_end_of_text_level_tag: + md_blocks.append(md_block) + + if is_self_closing: + logging.info("self-closing docbook '%s'", tag) + md_block = {'type': "self-closing tag", + 'text': deindented_line, + } + is_self_closing = 0 + continue + + logging.info("new markup '%s'", tag) + md_block = {'type': "markup", + 'text': deindented_line, + 'start': '<' + tag + '>', + 'end': '</' + tag + '>', + 'depth': 0, + } + if re.search(r'<\/%s>' % tag, deindented_line): + md_block["closed"] = 1 + + continue + else: + if tag in MD_TEXT_LEVEL_ELEMENTS: + logging.info("text level docbook '%s' in '%s' state", tag, md_block["type"]) + # TODO(ensonic): handle nesting + if not scanning_for_end_of_text_level_tag: + if not re.search(r'<\/%s>' % tag, deindented_line): + logging.info("new text level markup '%s'", tag) + md_block["start"] = '<' + tag + '>' + md_block["end"] = '</' + tag + '>' + md_block.pop("closed", None) + logging.info("scanning for end of '%s'", tag) + + else: + if md_block["end"] in deindented_line: + md_block["closed"] = 1 + logging.info("found end of '%s'", tag) + elif li_match: + # li + md_blocks.append(md_block) + indentation = li_match.group(1) + md_block = {'type': "li", + 'ordered': 0, + 'indentation': indentation, + 'marker': "[*+-]", + 'first': 1, + 'last': 1, + 'lines': [re.sub(r'^[ ]{0,4}', '', li_match.group(2))], + } + continue + elif quote_match: + md_blocks.append(md_block) + md_block = {'type': "quote", + 'lines': [quote_match.group(1)], + } + continue + + # list item + list_item_match = re.search(r'^([ ]{0,4})\d+[.][ ]+(.*)', line) + if list_item_match: + md_blocks.append(md_block) + indentation = list_item_match.group(1) + md_block = {'type': "li", + 'ordered': 1, + 'indentation': indentation, + 'marker': "\\d+[.]", + 'first': 1, + 'last': 1, + 'lines': [re.sub(r'^[ ]{0,4}', '', list_item_match.group(2))], + } + continue + + # paragraph + if md_block["type"] == "paragraph": + if "interrupted" in md_block: + md_blocks.append(md_block) + md_block = {'type': "paragraph", + 'text': line, + } + logging.info("new paragraph due to interrupted") + else: + md_block["text"] += "\n" + line + logging.info("add to paragraph: '%s'", line) + + else: + md_blocks.append(md_block) + md_block = {'type': "paragraph", + 'text': line, + } + logging.info("new paragraph due to different block type") + + md_blocks.append(md_block) + md_blocks.pop(0) + + return md_blocks + + +def MarkDownParseSpanElementsInner(text, markersref): + markup = '' + markers = {i: 1 for i in markersref} + + while text != '': + closest_marker = '' + closest_marker_position = -1 + text_marker = '' + offset = 0 + markers_rest = [] + + for marker, use in markers.items(): + if not use: + continue + + marker_position = text.find(marker) + + if marker_position < 0: + markers[marker] = 0 + continue + + if closest_marker == '' or marker_position < closest_marker_position: + closest_marker = marker + closest_marker_position = marker_position + + if closest_marker_position >= 0: + text_marker = text[closest_marker_position:] + + if text_marker == '': + markup += text + text = '' + continue + + markup += text[:closest_marker_position] + text = text[closest_marker_position:] + markers_rest = {k: v for k, v in markers.items() if v and k != closest_marker} + + if closest_marker == '![' or closest_marker == '[': + # 'id-ref' : local id reference + # 'title' : link short description/alt-text/tooltip + # 'a' : linked text + # 'href' : external link + # 'is-media': is link to media object + element = None + + # FIXME: '(?R)' is a recursive subpattern + # match a [...] block with no ][ inside or this thing again + # m = re.search(r'\[((?:[^][]|(?R))*)\]', text) + m = re.search(r'\[((?:[^][])*)\]', text) + if ']' in text and m: + element = {'is-media': text[0] == '!', + 'a': EscapeEntities(m.group(1)), + } + + offset = len(m.group(0)) + if element['is-media']: + offset += 1 + logging.debug("Recursive md-expr match: off=%d, text='%s', match='%s'", offset, text, m.group(1)) + + remaining_text = text[offset:] + # (link "alt-text") + m2 = re.search(r'''^\([ ]*([^)'"]*?)(?:[ ]+['"](.+?)['"])?[ ]*\)''', remaining_text) + # [id-reference] + m3 = re.search(r'^\s*\[([^\]<]*?)\]', remaining_text) + if m2: + element['href'] = m2.group(1) + if m2.group(2): + element['title'] = m2.group(2) + offset += len(m2.group(0)) + elif m3: + element['id-ref'] = m3.group(1) + offset += len(m3.group(0)) + else: + element = None + + if element: + logging.debug("output link for", element) + + if 'href' in element: + element['href'] = EscapeEntities(element['href']) + + if element['is-media']: + # media link + markup += '<inlinemediaobject><imageobject><imagedata fileref="' + \ + element['href'] + '"></imagedata></imageobject>' + + if 'a' in element: + markup += "<textobject><phrase>" + element['a'] + "</phrase></textobject>" + + markup += "</inlinemediaobject>" + elif 'id-ref' in element: + # internal link + element['a'] = MarkDownParseSpanElementsInner(element['a'], markers_rest) + markup += '<link linkend="' + element['id-ref'] + '"' + + if 'title' in element: + # title attribute not supported + pass + + markup += '>' + element['a'] + "</link>" + else: + # external link + element['a'] = MarkDownParseSpanElementsInner(element['a'], markers_rest) + markup += '<ulink url="' + element['href'] + '"' + + if 'title' in element: + # title attribute not supported + pass + + markup += '>' + element['a'] + "</ulink>" + + else: + markup += closest_marker + if closest_marker == '![': + offset = 2 + else: + offset = 1 + + elif closest_marker == '<': + m4 = re.search(r'^<(https?:[\/]{2}[^\s]+?)>', text, flags=re.I) + m5 = re.search(r'^<([A-Za-z0-9._-]+?@[A-Za-z0-9._-]+?)>', text) + m6 = re.search(r'^<[^>]+?>', text) + if m4: + element_url = EscapeEntities(m4.group(1)) + + markup += '<ulink url="' + element_url + '">' + element_url + '</ulink>' + offset = len(m4.group(0)) + elif m5: + markup += "<ulink url=\"mailto:" + m5.group(1) + "\">" + m5.group(1) + "</ulink>" + offset = len(m5.group(0)) + elif m6: + markup += m6.group(0) + offset = len(m6.group(0)) + else: + markup += "<" + offset = 1 + + elif closest_marker == "\\": + special_char = '' + if len(text) > 1: + special_char = text[1] + if special_char in MD_ESCAPABLE_CHARS or special_char in MD_GTK_ESCAPABLE_CHARS: + markup += special_char + offset = 2 + else: + markup += "\\" + offset = 1 + + elif closest_marker == "`": + m7 = re.search(r'^(`+)([^`]+?)\1(?!`)', text) + if m7: + element_text = EscapeEntities(m7.group(2)) + markup += "<literal>" + element_text + "</literal>" + offset = len(m7.group(0)) + else: + markup += "`" + offset = 1 + + elif closest_marker == "@": + # Convert '@param()' + # FIXME: we could make those also links ($symbol.$2), but that would be less + # useful as the link target is a few lines up or down + m7 = re.search(r'^(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)', text) + m8 = re.search(r'^(\A|[^\\])\@(\w+((\.|->)\w+)*)', text) + m9 = re.search(r'^\\\@', text) + if m7: + markup += m7.group(1) + "<parameter>" + m7.group(2) + "()</parameter>\n" + offset = len(m7.group(0)) + elif m8: + # Convert '@param', but not '\@param'. + markup += m8.group(1) + "<parameter>" + m8.group(2) + "</parameter>\n" + offset = len(m8.group(0)) + elif m9: + markup += r"\@" + offset = len(m9.group(0)) + else: + markup += "@" + offset = 1 + + elif closest_marker == '#': + m10 = re.search(r'^(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)', text) + m11 = re.search(r'^(\A|[^\\])#([\w\-:\.]+[\w]+)', text) + m12 = re.search(r'^\\#', text) + if m10: + # handle #Object.func() + markup += m10.group(1) + MakeXRef(m10.group(2), tagify(m10.group(2) + "()", "function")) + offset = len(m10.group(0)) + elif m11: + # Convert '#symbol', but not '\#symbol'. + markup += m11.group(1) + MakeHashXRef(m11.group(2), "type") + offset = len(m11.group(0)) + elif m12: + markup += '#' + offset = len(m12.group(0)) + else: + markup += '#' + offset = 1 + + elif closest_marker == "%": + m12 = re.search(r'^(\A|[^\\])\%(-?\w+)', text) + m13 = re.search(r'^\\%', text) + if m12: + # Convert '%constant', but not '\%constant'. + # Also allow negative numbers, e.g. %-1. + markup += m12.group(1) + MakeXRef(m12.group(2), tagify(m12.group(2), "literal")) + offset = len(m12.group(0)) + elif m13: + markup += r"\%" + offset = len(m13.group(0)) + else: + markup += "%" + offset = 1 + + if offset > 0: + text = text[offset:] + + return markup + + +def MarkDownParseSpanElements(text): + markers = ["\\", '<', '![', '[', "`", '%', '#', '@'] + + text = MarkDownParseSpanElementsInner(text, markers) + + # Convert 'function()' or 'macro()'. + # if there is abc_*_def() we don't want to make a link to _def() + # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/ + def f(m): + return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2) + "()", "function")) + text = re.sub(r'([^\*.\w])(\w+)\s*\(\)', f, text) + return text + + +def EscapeEntities(text): + return text.replace('&', '&').replace('<', '<').replace('>', '>') + + +def ReplaceEntities(text): + entities = [["<", '<'], + [">", '>'], + ["*", '*'], + ["#", '#'], + ["%", '%'], + [":", ':'], + [""", '"'], + ["'", "'"], + [" ", ' '], + ["&", '&'], # Do this last, or the others get messed up. + ] + + for i in entities: + text = re.sub(i[0], i[1], text) + return text + + +def MarkDownOutputDocBook(blocksref, symbol, context): + output = '' + blocks = blocksref + + for block in blocks: + # $output += "\n<!-- beg type='" . $block->{"type"} . "'-->\n" + + if block["type"] == "paragraph": + text = MarkDownParseSpanElements(block["text"]) + if context == "li" and output == '': + if 'interrupted' in block: + output += "\n<para>%s</para>\n" % text + else: + output += "<para>%s</para>" % text + if len(blocks) > 1: + output += "\n" + else: + output += "<para>%s</para>\n" % text + + elif block["type"] == "heading": + + title = MarkDownParseSpanElements(block["text"]) + + if block["level"] == 1: + tag = "refsect2" + else: + tag = "refsect3" + + text = MarkDownParseLines(block["lines"], symbol, "heading") + if 'id' in block: + output += "<%s id=\"%s\">" % (tag, block["id"]) + else: + output += "<%s>" % tag + + output += "<title>%s%s\n" % (title, text, tag) + elif block["type"] == "li": + tag = "itemizedlist" + + if "first" in block: + if block["ordered"]: + tag = "orderedlist" + output += "<%s>\n" % tag + + if "interrupted" in block: + block["lines"].append('') + + text = MarkDownParseLines(block["lines"], symbol, "li") + output += "" + text + "\n" + if 'last' in block: + if block["ordered"]: + tag = "orderedlist" + output += "\n" % tag + + elif block["type"] == "quote": + text = MarkDownParseLines(block["lines"], symbol, "quote") + output += "
\n%s
\n" % text + elif block["type"] == "code": + tag = "programlisting" + + if "language" in block: + if block["language"] == "plain": + output += "\n" % tag + elif block["type"] == "markup": + text = ExpandAbbreviations(symbol, block["text"]) + output += text + "\n" + else: + output += block["text"] + "\n" + + # $output += "\n\n" + return output + + +def MarkDownParseLines(lines, symbol, context): + logging.info('md parse: ctx=%s, [%s]', context, '\n'.join(lines)) + blocks = MarkDownParseBlocks(lines, symbol, context) + output = MarkDownOutputDocBook(blocks, symbol, context) + return output + + +def MarkDownParse(text, symbol): + """Converts mark down syntax to the respective docbook. + + http://de.wikipedia.org/wiki/Markdown + Inspired by the design of ParseDown + http://parsedown.org/ + Copyright (c) 2013 Emanuil Rusev, erusev.com + + SUPPORTED MARKDOWN + ================== + + Atx-style Headers + ----------------- + + # Header 1 + + ## Header 2 ## + + Setext-style Headers + -------------------- + + Header 1 + ======== + + Header 2 + -------- + + Ordered (unnested) Lists + ------------------------ + + 1. item 1 + + 1. item 2 with loooong + description + + 3. item 3 + + Note: we require a blank line above the list items + """ + # TODO(ensonic): it would be nice to add id parameters to the refsect2 elements + + return MarkDownParseLines(text.splitlines(), symbol, '') diff --git a/gtk-doc-for-gtk4/gtkdoc/meson.build b/gtk-doc-for-gtk4/gtkdoc/meson.build new file mode 100644 index 0000000000..0dfb825ec3 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/meson.build @@ -0,0 +1,45 @@ +config_py = configuration_data() +config_py.set('prefix', get_option('prefix')) +config_py.set('datarootdir', join_paths('${prefix}', get_option('datadir'))) +config_py.set('datadir', '${datarootdir}') + +config_py.set('DBLATEX', dblatex_prg_path) +config_py.set('FOP', fop_prg_path) +config_py.set('PKG_CONFIG', pkgconfig_prg_path) +config_py.set('XSLTPROC', xsltproc_prg_path) + +config_py.set('VERSION', version) +config_py.set('EXEEXT', '') + +configure_file( + input: 'config_data.py.in', + output: 'config_data.py', + configuration: config_py, + install: true, + install_dir: join_paths( + pkgpythondir, + 'gtkdoc', + ), +) + +gtkdoc_sources = [ + '__init__.py', + 'check.py', + 'common.py', + 'config.py', + 'fixxref.py', + 'highlight.py', + 'md_to_db.py', + 'mkdb.py', + 'mkhtml.py', + 'mkhtml2.py', + 'mkman.py', + 'mkpdf.py', + 'rebase.py', + 'scan.py', + 'scangobj.py', +] + +install_data(gtkdoc_sources, + install_dir: join_paths(pkgpythondir, 'gtkdoc') +) diff --git a/gtk-doc-for-gtk4/gtkdoc/mkdb.py b/gtk-doc-for-gtk4/gtkdoc/mkdb.py new file mode 100644 index 0000000000..539f5135ab --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/mkdb.py @@ -0,0 +1,4947 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +Creates the DocBook files from the source comments. +""" + +from collections import OrderedDict +import logging +import os +import re +import string + +from . import common, md_to_db + +# Options +MODULE = None +DB_OUTPUT_DIR = None +INLINE_MARKUP_MODE = None +NAME_SPACE = '' +ROOT_DIR = '.' + +# These global arrays store information on signals. Each signal has an entry +# in each of these arrays at the same index, like a multi-dimensional array. +SignalObjects = [] # The GtkObject which emits the signal. +SignalNames = [] # The signal name. +SignalReturns = [] # The return type. +SignalFlags = [] # Flags for the signal +SignalPrototypes = [] # The rest of the prototype of the signal handler. + +# These global arrays store information on Args. Each Arg has an entry +# in each of these arrays at the same index, like a multi-dimensional array. +ArgObjects = [] # The GtkObject which has the Arg. +ArgNames = [] # The Arg name. +ArgTypes = [] # The Arg type - gint, GtkArrowType etc. +ArgFlags = [] # How the Arg can be used - readable/writable etc. +ArgNicks = [] # The nickname of the Arg. +ArgBlurbs = [] # Docstring of the Arg. +ArgDefaults = [] # Default value of the Arg. +ArgRanges = [] # The range of the Arg type + +ActionObjects = [] +ActionNames = [] +ActionParams = [] +ActionProperties = [] + +# These global hashes store declaration info keyed on a symbol name. +Declarations = {} +DeclarationTypes = {} +DeclarationConditional = {} +DeclarationOutput = {} +Deprecated = {} +Since = {} +StabilityLevel = {} +StructHasTypedef = {} + +# These global hashes store the existing documentation. +SymbolDocs = {} +SymbolParams = {} +SymbolAnnotations = {} + +# These global hashes store documentation scanned from the source files. +SourceSymbolDocs = {} +SourceSymbolParams = {} +SymbolSourceLocation = {} + +# all documentation goes in here, so we can do coverage analysis +AllSymbols = {} +AllIncompleteSymbols = {} +AllUnusedSymbols = {} +AllDocumentedSymbols = {} + +# Undeclared yet documented symbols +UndeclaredSymbols = {} + +# These global arrays store GObject, subclasses and the hierarchy (also of +# non-object derived types). +Objects = [] +ObjectLevels = [] +ObjectRoots = {} + +Interfaces = {} +Prerequisites = {} + +# holds the symbols which are mentioned in -sections.txt and in which +# section they are defined +KnownSymbols = {} # values are 1 for public symbols and 0 otherwise +SymbolSection = {} +SymbolSectionId = {} + +# collects index entries +IndexEntriesFull = {} +IndexEntriesSince = {} +IndexEntriesDeprecated = {} + +# Standard C preprocessor directives, which we ignore for '#' abbreviations. +PreProcessorDirectives = { + 'assert', 'define', 'elif', 'else', 'endif', 'error', 'if', 'ifdef', 'ifndef', + 'include', 'line', 'pragma', 'unassert', 'undef', 'warning' +} + +# remember used annotation (to write minimal glossary) +AnnotationsUsed = {} + +# the regexp that parses the annotation is in ScanSourceFile() +AnnotationDefinition = { + # the GObjectIntrospection annotations are defined at: + # https://live.gnome.org/GObjectIntrospection/Annotations + 'allow-none': "NULL is OK, both for passing and for returning.", + 'nullable': "NULL may be passed as the value in, out, in-out; or as a return value.", + 'not nullable': "NULL must not be passed as the value in, out, in-out; or as a return value.", + 'optional': "NULL may be passed instead of a pointer to a location.", + 'not optional': "NULL must not be passed as the pointer to a location.", + 'array': "Parameter points to an array of items.", + 'attribute': "Deprecated free-form custom annotation, replaced by (attributes) annotation.", + 'attributes': "Free-form key-value pairs.", + 'closure': "This parameter is a 'user_data', for callbacks; many bindings can pass NULL here.", + 'constructor': "This symbol is a constructor, not a static method.", + 'destroy': "This parameter is a 'destroy_data', for callbacks.", + 'default': "Default parameter value (in case a function which shadows this one via rename-to has fewer parameters).", + 'element-type': "Generics and defining elements of containers and arrays.", + 'error-domains': "Typed errors. Similar to throws in Java.", + 'foreign': "This is a foreign struct.", + 'get-value-func': "The specified function is used to convert a struct from a GValue, must be a GTypeInstance.", + 'in': "Parameter for input. Default is transfer none.", + 'inout': "Parameter for input and for returning results. Default is transfer full.", + 'in-out': "Parameter for input and for returning results. Default is transfer full.", + 'method': "This is a method", + 'not-error': "A GError parameter is not to be handled like a normal GError.", + 'out': "Parameter for returning results. Default is transfer full.", + 'out caller-allocates': "Out parameter, where caller must allocate storage.", + 'out callee-allocates': "Out parameter, where callee must allocate storage.", + 'ref-func': "The specified function is used to ref a struct, must be a GTypeInstance.", + 'rename-to': "Rename the original symbol's name to SYMBOL.", + 'scope call': "The callback is valid only during the call to the method.", + 'scope async': "The callback is valid until first called.", + 'scope notified': "The callback is valid until the GDestroyNotify argument is called.", + 'set-value-func': "The specified function is used to convert from a struct to a GValue, must be a GTypeInstance.", + 'skip': "Exposed in C code, not necessarily available in other languages.", + 'transfer container': "Free data container after the code is done.", + 'transfer floating': "Alias for transfer none, used for objects with floating refs.", + 'transfer full': "Free data after the code is done.", + 'transfer none': "Don't free data after the code is done.", + 'type': "Override the parsed C type with given type.", + 'unref-func': "The specified function is used to unref a struct, must be a GTypeInstance.", + 'virtual': "This is the invoker for a virtual method.", + 'value': "The specified value overrides the evaluated value of the constant.", + # Stability Level definition + # https://bugzilla.gnome.org/show_bug.cgi?id=170860 + 'Stable': '''The intention of a Stable interface is to enable arbitrary third parties to +develop applications to these interfaces, release them, and have confidence that +they will run on all minor releases of the product (after the one in which the +interface was introduced, and within the same major release). Even at a major +release, incompatible changes are expected to be rare, and to have strong +justifications. +''', + 'Unstable': '''Unstable interfaces are experimental or transitional. They are typically used to +give outside developers early access to new or rapidly changing technology, or +to provide an interim solution to a problem where a more general solution is +anticipated. No claims are made about either source or binary compatibility from +one minor release to the next. + +The Unstable interface level is a warning that these interfaces are subject to +change without warning and should not be used in unbundled products. + +Given such caveats, customer impact need not be a factor when considering +incompatible changes to an Unstable interface in a major or minor release. +Nonetheless, when such changes are introduced, the changes should still be +mentioned in the release notes for the affected release. +''', + 'Private': '''An interface that can be used within the GNOME stack itself, but that is not +documented for end-users. Such functions should only be used in specified and +documented ways. +''', +} + +# Function and other declaration output settings. +RETURN_TYPE_FIELD_WIDTH = 20 +MAX_SYMBOL_FIELD_WIDTH = 40 + +# XML header +doctype_header = None + +# docbook templates +DB_REFENTRY = string.Template('''${header} + + +${title} +3 +${MODULE} Library${image} + + +${title} +${short_desc} + +${stability} +${functions_synop}${args_synop}${signals_synop}${actions_synop}${object_anchors}${other_synop}${hierarchy}${prerequisites}${derived}${interfaces}${implementations} +${include_output} + +Description +${extralinks}${long_desc} + + +Functions +${functions_details} + +${other_desc}${args_desc}${signals_desc}${actions_desc}${see_also} + +''') + +DB_REFSECT1_SYNOPSIS3 = string.Template(''' +${title} + + + + + + +${content} + + + + +''') + +DB_REFSECT1_SYNOPSIS2 = string.Template(''' +${title} + + + + + +${content} + + + + +''') + +DB_REFSECT1_DESC = string.Template(''' +${title} +${content} + +''') + + +def Run(options): + global MODULE, INLINE_MARKUP_MODE, NAME_SPACE, DB_OUTPUT_DIR, doctype_header + + logging.info('options: %s', str(options.__dict__)) + + # We should pass the options variable around instead of this global variable horror + # but too much of the code expects these to be around. Fix this once the transition is done. + MODULE = options.module + INLINE_MARKUP_MODE = options.xml_mode or options.sgml_mode + NAME_SPACE = options.name_space + DB_OUTPUT_DIR = options.output_dir or os.path.join(ROOT_DIR, "xml") + + main_sgml_file = options.main_sgml_file + if not main_sgml_file: + # backwards compatibility + if os.path.exists(MODULE + "-docs.sgml"): + main_sgml_file = MODULE + "-docs.sgml" + else: + main_sgml_file = MODULE + "-docs.xml" + + # -- phase 1: read files produced by previous tools and scane sources + + # extract docbook header or define default + doctype_header = GetDocbookHeader(main_sgml_file) + + ReadKnownSymbols(os.path.join(ROOT_DIR, MODULE + "-sections.txt")) + ReadSignalsFile(os.path.join(ROOT_DIR, MODULE + ".signals")) + ReadArgsFile(os.path.join(ROOT_DIR, MODULE + ".args")) + ReadActionsFile(os.path.join(ROOT_DIR, MODULE + ".actions")) + obj_tree = ReadObjectHierarchy(os.path.join(ROOT_DIR, MODULE + ".hierarchy")) + ReadInterfaces(os.path.join(ROOT_DIR, MODULE + ".interfaces")) + ReadPrerequisites(os.path.join(ROOT_DIR, MODULE + ".prerequisites")) + + ReadDeclarationsFile(os.path.join(ROOT_DIR, MODULE + "-decl.txt"), 0) + if os.path.isfile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt")): + ReadDeclarationsFile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt"), 1) + + logging.info("Data files read") + + # -- phase 2: scan sources + + # TODO: move this to phase 3 once we fixed the call to OutputProgramDBFile() + if not os.path.isdir(DB_OUTPUT_DIR): + os.mkdir(DB_OUTPUT_DIR) + + # Scan sources + if options.source_suffixes: + suffix_list = ['.' + ext for ext in options.source_suffixes.split(',')] + else: + suffix_list = ['.c', '.h'] + + source_dirs = options.source_dir + ignore_files = options.ignore_files and options.ignore_files.split(' ') or [] + logging.info("Ignored files: " + options.ignore_files) + + for sdir in source_dirs: + abs_ignored_files = [os.path.join(sdir, x) for x in ignore_files] + ReadSourceDocumentation(sdir, suffix_list, abs_ignored_files) + + logging.info("Sources scanned") + + # -- phase 3: write docbook files + + changed, book_top, book_bottom = OutputDB(os.path.join(ROOT_DIR, MODULE + "-sections.txt"), options) + OutputBook(main_sgml_file, book_top, book_bottom, obj_tree) + + # If any of the DocBook files have changed, update the timestamp file (so + # it can be used for Makefile dependencies). + if changed or not os.path.exists(os.path.join(ROOT_DIR, "sgml.stamp")): + # TODO: MakeIndexterms() uses NAME_SPACE, but also fills IndexEntriesFull + # which DetermineNamespace is using + # Can we use something else? + # no: AllSymbols, KnownSymbols + # IndexEntriesFull: consist of all symbols from sections file + signals and properties + # + # logging.info('# index_entries_full=%d, # declarations=%d', + # len(IndexEntriesFull), len(Declarations)) + # logging.info('known_symbols - index_entries_full: ' + str(Declarations.keys() - IndexEntriesFull.keys())) + + # try to detect the common prefix + # GtkWidget, GTK_WIDGET, gtk_widget -> gtk + if NAME_SPACE == '': + NAME_SPACE = DetermineNamespace(IndexEntriesFull.keys()) + + logging.info('namespace prefix ="%s"', NAME_SPACE) + + OutputObjectTree(obj_tree) + OutputObjectList(Objects) + + OutputIndex("api-index-full", IndexEntriesFull) + OutputIndex("api-index-deprecated", IndexEntriesDeprecated) + OutputSinceIndexes() + OutputAnnotationGlossary() + + with open(os.path.join(ROOT_DIR, 'sgml.stamp'), 'w') as h: + h.write('timestamp') + + logging.info("All files created: %d", changed) + + +def OutputObjectList(obj_list): + """This outputs the alphabetical list of objects, in a columned table.""" + # FIXME: Currently this also outputs ancestor objects which may not actually + # be in this module. + + # TODO(ensonic): consider not writing this unconditionally + if not obj_list: + return + + cols = 3 + + # FIXME: use .xml + old_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.sgml") + new_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.new") + + OUTPUT = open(new_object_index, 'w', encoding='utf-8') + + OUTPUT.write('''%s + + + + + + +''' % (MakeDocHeader("informaltable"), cols)) + + count = 0 + object = None + for object in sorted(Objects): + xref = MakeXRef(object) + if count % cols == 0: + OUTPUT.write("\n") + OUTPUT.write("%s\n" % xref) + if count % cols == cols - 1: + OUTPUT.write("\n") + count += 1 + + if count % cols > 0: + OUTPUT.write("\n") + + OUTPUT.write('''\n''') + OUTPUT.close() + + common.UpdateFileIfChanged(old_object_index, new_object_index, 0) + + +def trim_leading_and_trailing_nl(text): + """Trims extra newlines. + + Leaves a single trailing newline. + + Args: + text (str): the text block to trim. May contain newlines. + + Returns: + (str): trimmed text + """ + text = re.sub(r'^\n*', '', text) + return re.sub(r'\n+$', '\n', text) + + +def trim_white_spaces(text): + """Trims extra whitespace. + + Empty lines inside a block are preserved. All whitespace and the end is + replaced with a single newline. + + Args: + text (str): the text block to trim. May contain newlines. + + Returns: + (str): trimmed text + """ + + # strip trailing spaces on every line + return re.sub(r'\s+$', '\n', text.lstrip(), flags=re.MULTILINE) + + +def make_refsect1_synopsis(tmpl, content, title, section_id, section_type, role=None): + # TODO(ensonic): canonicalize xml to use the same string for section_type + # and role. Needs fixes on gtk-doc.xsl + if role is None: + role = section_type.replace('-', '_') + + return tmpl.substitute({ + 'content': content, + 'role': role, + 'section_id': section_id, + 'title': title, + 'type': section_type, + }) + + +def make_refsect1_synopsis2(content, title, section_id, section_type, role=None): + return make_refsect1_synopsis(DB_REFSECT1_SYNOPSIS2, content, title, section_id, section_type, role) + + +def make_refsect1_synopsis3(content, title, section_id, section_type, role=None): + return make_refsect1_synopsis(DB_REFSECT1_SYNOPSIS3, content, title, section_id, section_type, role) + + +def make_refsect1_desc(content, title, section_id, section_type, role=None): + content = trim_white_spaces(content) + if content == '': + return '' + + # TODO(ensonic): canonicalize xml to use the same string for section_type + # and role. Needs fixes on gtk-doc.xsl + if role is None: + role = section_type.replace('-', '_') + + return DB_REFSECT1_DESC.substitute({ + 'content': content, + 'role': role, + 'section_id': section_id, + 'title': title, + 'type': section_type, + }) + + +def OutputDB(file, options): + """Generate docbook files. + + This collects the output for each section of the docs, and outputs each file + when the end of the section is found. + + Args: + file (str): the $MODULE-sections.txt file which contains all of the + functions/macros/structs etc. being documented, organised + into sections and subsections. + options: commandline options + """ + + logging.info("Reading: %s", file) + INPUT = open(file, 'r', encoding='utf-8') + filename = '' + book_top = '' + book_bottom = '' + includes = options.default_includes or '' + section_includes = '' + in_section = 0 + title = '' + section_id = '' + subsection = '' + num_symbols = 0 + changed = 0 + functions_synop = '' + other_synop = '' + functions_details = '' + other_details = '' + other_desc = '' + signals_synop = '' + signals_desc = '' + args_synop = '' + child_args_synop = '' + style_args_synop = '' + args_desc = '' + child_args_desc = '' + style_args_desc = '' + actions_synop = '' + actions_desc = '' + hierarchy_str = '' + hierarchy = [] + interfaces = '' + implementations = '' + prerequisites = '' + derived = '' + file_objects = [] + file_def_line = {} + symbol_def_line = {} + + MergeSourceDocumentation() + + line_number = 0 + for line in INPUT: + line_number += 1 + + if line.startswith('#'): + continue + + logging.info("section file data: %d: %s", line_number, line) + + m1 = re.search(r'^', line, re.I) + m2 = re.search(r'^(.*)<\/TITLE', line) + m3 = re.search(r'^<FILE>(.*)<\/FILE>', line) + m4 = re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line) + m5 = re.search(r'^(\S+)', line) + + if line.startswith('<SECTION>'): + num_symbols = 0 + in_section = False + file_objects = [] + symbol_def_line = {} + + elif m1: + other_synop += "\n" + functions_synop += "\n" + subsection = m1.group(1) + + elif line.startswith('<SUBSECTION>'): + continue + elif m2: + title = m2.group(1) + logging.info("Section: %s", title) + + # We don't want warnings if object & class structs aren't used. + DeclarationOutput[title] = 1 + DeclarationOutput["%sClass" % title] = 1 + DeclarationOutput["%sIface" % title] = 1 + DeclarationOutput["%sInterface" % title] = 1 + + elif m3: + filename = m3.group(1) + if filename not in file_def_line: + file_def_line[filename] = line_number + else: + common.LogWarning(file, line_number, "Double <FILE>%s</FILE> entry. Previous occurrence on line %s." % + (filename, file_def_line[filename])) + if title == '': + key = filename + ":title" + if key in SourceSymbolDocs: + title = SourceSymbolDocs[key].rstrip() + + elif m4: + if in_section: + section_includes = m4.group(1) + else: + if options.default_includes: + common.LogWarning(file, line_number, "Default <INCLUDE> being overridden by command line option.") + else: + includes = m4.group(1) + + elif re.search(r'^<\/SECTION>', line): + logging.info("End of section: %s", title) + # TODO: also output if we have sections docs? + # long_desc = SymbolDocs.get(filename + ":long_description") + if num_symbols > 0: + # collect documents + book_bottom += " <xi:include href=\"xml/%s.xml\"/>\n" % filename + + key = filename + ":include" + if key in SourceSymbolDocs: + if section_includes: + common.LogWarning(file, line_number, "Section <INCLUDE> being overridden by inline comments.") + section_includes = SourceSymbolDocs[key] + + if section_includes == '': + section_includes = includes + + signals_synop = trim_leading_and_trailing_nl(signals_synop) + if signals_synop != '': + signals_synop = make_refsect1_synopsis3( + signals_synop, 'Signals', section_id, 'signals', 'signal_proto') + signals_desc = make_refsect1_desc(signals_desc, 'Signal Details', + section_id, 'signal-details', 'signals') + + args_synop = trim_leading_and_trailing_nl(args_synop) + if args_synop != '': + args_synop = make_refsect1_synopsis3(args_synop, 'Properties', section_id, 'properties') + args_desc = make_refsect1_desc(args_desc, 'Property Details', section_id, 'property-details') + + child_args_synop = trim_leading_and_trailing_nl(child_args_synop) + if child_args_synop != '': + args_synop += make_refsect1_synopsis3(child_args_synop, + 'Child Properties', section_id, 'child-properties') + args_desc += make_refsect1_desc(child_args_desc, 'Child Property Details', + section_id, 'child-property-details') + + style_args_synop = trim_leading_and_trailing_nl(style_args_synop) + if style_args_synop != '': + args_synop += make_refsect1_synopsis3(style_args_synop, + 'Style Properties', section_id, 'style-properties') + args_desc += make_refsect1_desc(style_args_desc, 'Style Property Details', + section_id, 'style-property-details') + + actions_synop = re.sub(r'^\n*', '', actions_synop) + actions_synop = re.sub(r'\n+$', '\n', actions_synop) + if actions_synop != '': + actions_synop = '''<refsect1 id="%s.actions" role="actions"> +<title role="actions.title">Actions + + + + + + +%s + + + + +''' % (section_id, actions_synop) + actions_desc = trim_leading_and_trailing_nl(actions_desc) + actions_desc = ''' +Action Details +%s + +''' % (section_id, actions_desc) + + hierarchy_str = AddTreeLineArt(hierarchy) + if hierarchy_str != '': + hierarchy_str = make_refsect1_desc('' + hierarchy_str + '\n', + 'Object Hierarchy', section_id, 'object-hierarchy') + + interfaces = make_refsect1_desc(interfaces, 'Implemented Interfaces', section_id, + 'implemented-interfaces', 'impl_interfaces') + implementations = make_refsect1_desc( + implementations, 'Known Implementations', section_id, 'implementations') + prerequisites = make_refsect1_desc(prerequisites, 'Prerequisites', section_id, 'prerequisites') + derived = make_refsect1_desc(derived, 'Known Derived Interfaces', section_id, 'derived-interfaces') + + functions_synop = trim_leading_and_trailing_nl(functions_synop) + if functions_synop != '': + functions_synop = make_refsect1_synopsis2( + functions_synop, 'Functions', section_id, 'functions', 'functions_proto') + + other_synop = trim_leading_and_trailing_nl(other_synop) + if other_synop != '': + other_synop = make_refsect1_synopsis2( + other_synop, 'Types and Values', section_id, 'other', 'other_proto') + other_desc += make_refsect1_desc(other_details, 'Types and Values', + section_id, 'other_details', 'details') + + file_changed = OutputDBFile(filename, title, section_id, + section_includes, + functions_synop, other_synop, + functions_details, other_desc, + signals_synop, signals_desc, + args_synop, args_desc, + actions_synop, actions_desc, + hierarchy_str, interfaces, + implementations, + prerequisites, derived, + file_objects, + options.default_stability) + if file_changed: + changed = True + + title = '' + section_id = '' + subsection = '' + in_section = 0 + section_includes = '' + functions_synop = '' + other_synop = '' + functions_details = '' + other_details = '' + other_desc = '' + signals_synop = '' + signals_desc = '' + args_synop = '' + child_args_synop = '' + style_args_synop = '' + args_desc = '' + child_args_desc = '' + style_args_desc = '' + actions_synop = '' + actions_desc = '' + hierarchy_str = '' + hierarchy = [] + interfaces = '' + implementations = '' + prerequisites = '' + derived = '' + + elif m5: + symbol = m5.group(1) + logging.info(' Symbol: "%s" in subsection: "%s"', symbol, subsection) + + # check for duplicate entries + if symbol not in symbol_def_line: + declaration = Declarations.get(symbol) + # FIXME: with this we'll output empty declaration + if declaration is not None: + if CheckIsObject(symbol): + file_objects.append(symbol) + + # We don't want standard macros/functions of GObjects, + # or private declarations. + if subsection != "Standard" and subsection != "Private": + synop, desc = OutputDeclaration(symbol, declaration) + type = DeclarationTypes[symbol] + + if type == 'FUNCTION' or type == 'USER_FUNCTION': + functions_synop += synop + functions_details += desc + elif type == 'MACRO' and re.search(symbol + r'\(', declaration): + functions_synop += synop + functions_details += desc + else: + other_synop += synop + other_details += desc + + sig_synop, sig_desc = GetSignals(symbol) + arg_synop, child_arg_synop, style_arg_synop, arg_desc, child_arg_desc, style_arg_desc = GetArgs( + symbol) + action_synop, action_desc = GetActions(symbol) + ifaces = GetInterfaces(symbol) + impls = GetImplementations(symbol) + prereqs = GetPrerequisites(symbol) + der = GetDerived(symbol) + hierarchy = GetHierarchy(symbol, hierarchy) + + signals_synop += sig_synop + signals_desc += sig_desc + args_synop += arg_synop + child_args_synop += child_arg_synop + style_args_synop += style_arg_synop + args_desc += arg_desc + child_args_desc += child_arg_desc + style_args_desc += style_arg_desc + actions_synop += action_synop + actions_desc += action_desc + interfaces += ifaces + implementations += impls + prerequisites += prereqs + derived += der + + # Note that the declaration has been output. + DeclarationOutput[symbol] = True + elif subsection != "Standard" and subsection != "Private": + UndeclaredSymbols[symbol] = True + common.LogWarning(file, line_number, "No declaration found for %s." % symbol) + + num_symbols += 1 + symbol_def_line[symbol] = line_number + + if section_id == '': + if title == '' and filename == '': + common.LogWarning(file, line_number, "Section has no title and no file.") + + # FIXME: one of those would be enough + # filename should be an internal detail for gtk-doc + if title == '': + title = filename + elif filename == '': + filename = title + + filename = filename.replace(' ', '_') + + section_id = SourceSymbolDocs.get(filename + ":section_id") + if section_id and section_id.strip() != '': + # Remove trailing blanks and use as is + section_id = section_id.rstrip() + elif CheckIsObject(title): + # GObjects use their class name as the ID. + section_id = common.CreateValidSGMLID(title) + else: + section_id = common.CreateValidSGMLID(MODULE + '-' + title) + + SymbolSection[symbol] = title + SymbolSectionId[symbol] = section_id + + else: + common.LogWarning(file, line_number, "Double symbol entry for %s. " + "Previous occurrence on line %d." % (symbol, symbol_def_line[symbol])) + INPUT.close() + + OutputMissingDocumentation() + OutputUndeclaredSymbols() + OutputUnusedSymbols() + + if options.outputallsymbols: + OutputAllSymbols() + + if options.outputsymbolswithoutsince: + OutputSymbolsWithoutSince() + + for filename in options.expand_content_files.split(): + file_changed = OutputExtraFile(filename) + if file_changed: + changed = True + + return (changed, book_top, book_bottom) + + +def DetermineNamespace(symbols): + """Find common set of characters. + + Args: + symbols (list): a list of symbols to scan for a common prefix + + Returns: + str: a common namespace prefix (might be empty) + """ + name_space = '' + pos = 0 + ratio = 0.0 + while True: + prefix = {} + letter = '' + for symbol in symbols: + if name_space == '' or name_space.lower() in symbol.lower(): + if len(symbol) > pos: + letter = symbol[pos:pos + 1] + # stop prefix scanning + if letter == "_": + # stop on "_" + break + # Should we also stop on a uppercase char, if last was lowercase + # GtkWidget, if we have the 'W' and had the 't' before + # or should we count upper and lowercase, and stop one 2nd uppercase, if we already had a lowercase + # GtkWidget, the 'W' would be the 2nd uppercase and with 't','k' we had lowercase chars before + # need to recound each time as this is per symbol + ul = letter.upper() + if ul in prefix: + prefix[ul] += 1 + else: + prefix[ul] = 1 + + if letter != '' and letter != "_": + maxletter = '' + maxsymbols = 0 + for letter in prefix.keys(): + logging.debug("ns prefix: %s: %s", letter, prefix[letter]) + if prefix[letter] > maxsymbols: + maxletter = letter + maxsymbols = prefix[letter] + + ratio = float(len(symbols)) / prefix[maxletter] + logging.debug('most symbols start with %s, that is %f', maxletter, (100 * ratio)) + if ratio > 0.9: + # do another round + name_space += maxletter + + pos += 1 + + else: + ratio = 0.0 + + if ratio < 0.9: + break + return name_space + + +def OutputIndex(basename, apiindex): + """Writes an index that can be included into the main-document into an tag. + + Args: + basename (str): name of the index file without extension + apiindex (dict): the index data + """ + old_index = os.path.join(DB_OUTPUT_DIR, basename + '.xml') + new_index = os.path.join(DB_OUTPUT_DIR, basename + '.new') + lastletter = " " + divopen = 0 + symbol = None + short_symbol = None + + OUTPUT = open(new_index, 'w') + + OUTPUT.write(MakeDocHeader("indexdiv") + "\n\n" % basename) + + logging.info("generate %s index (%d entries) with namespace %s", basename, len(apiindex), NAME_SPACE) + + # do a case insensitive sort while chopping off the prefix + mapped_keys = [ + { + 'original': x, + 'short': re.sub(r'^' + NAME_SPACE + r'\_?(.*)', r'\1', x.upper(), flags=re.I), + } for x in apiindex.keys()] + sorted_keys = sorted(mapped_keys, key=lambda d: (d['short'], d['original'])) + + for key in sorted_keys: + symbol = key['original'] + short = key['short'] + if short != '': + short_symbol = short + else: + short_symbol = symbol + + # generate a short symbol description + symbol_desc = '' + symbol_section = '' + symbol_section_id = '' + symbol_type = '' + if symbol in DeclarationTypes: + symbol_type = DeclarationTypes[symbol].lower() + + if symbol_type == '': + logging.info("trying symbol %s", symbol) + m1 = re.search(r'(.*)::(.*)', symbol) + m2 = re.search(r'(.*):(.*)', symbol) + m3 = re.search(r'(.*)\|(.*)', symbol) + if m1: + oname = m1.group(1) + osym = m1.group(2) + logging.info(" trying object signal %s:%s in %d signals", oname, osym, len(SignalNames)) + for name in SignalNames: + logging.info(" " + name) + if name == osym: + symbol_type = "object signal" + if oname in SymbolSection: + symbol_section = SymbolSection[oname] + symbol_section_id = SymbolSectionId[oname] + break + elif m2: + oname = m2.group(1) + osym = m2.group(2) + logging.info(" trying object property %s::%s in %d properties", oname, osym, len(ArgNames)) + for name in ArgNames: + logging.info(" " + name) + if name == osym: + symbol_type = "object property" + if oname in SymbolSection: + symbol_section = SymbolSection[oname] + symbol_section_id = SymbolSectionId[oname] + break + elif m3: + oname = m3.group(1) + osym = m3.group(2) + logging.info(" trying action %s|%s in %d actions", oname, osym, len(ActionNames)) + for name in ActionNames: + logging.info(" " + name) + if name == osym: + symbol_type = "action" + if oname in SymbolSection: + symbol_section = SymbolSection[oname] + symbol_section_id = SymbolSectionId[oname] + break + else: + if symbol in SymbolSection: + symbol_section = SymbolSection[symbol] + symbol_section_id = SymbolSectionId[symbol] + + if symbol_type != '': + symbol_desc = ", " + symbol_type + if symbol_section != '': + symbol_desc += " in %s" % (symbol_section_id, symbol_section) + # symbol_desc +=" in " + ExpandAbbreviations(symbol, "#symbol_section") + + curletter = short_symbol[0].upper() + ixid = apiindex[symbol] + + logging.info(" add symbol %s with %s to index in section '%s' (derived from %s)", + symbol, ixid, curletter, short_symbol) + + if curletter != lastletter: + lastletter = curletter + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("%s\n" % curletter) + divopen = True + + OUTPUT.write('%s%s\n' % + (ixid, ixid, symbol, symbol_desc)) + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("\n") + OUTPUT.close() + + common.UpdateFileIfChanged(old_index, new_index, 0) + + +def OutputSinceIndexes(): + """Generate the 'since' api index files.""" + for version in sorted(set(Since.values())): + logging.info("Since : [%s]", version) + index = {x: IndexEntriesSince[x] for x in IndexEntriesSince.keys() if Since[x] == version} + OutputIndex("api-index-" + version, index) + + +def OutputAnnotationGlossary(): + """Writes a glossary of the used annotation terms. + + The glossary file can be included into the main document. + """ + # if there are no annotations used return + if not AnnotationsUsed: + return + + old_glossary = os.path.join(DB_OUTPUT_DIR, "annotation-glossary.xml") + new_glossary = os.path.join(DB_OUTPUT_DIR, "annotation-glossary.new") + lastletter = " " + divopen = False + + # add acronyms that are referenced from acronym text + rerun = True + while rerun: + rerun = False + for annotation in AnnotationsUsed: + if annotation not in AnnotationDefinition: + continue + m = re.search(r'([\w ]+)<\/acronym>', AnnotationDefinition[annotation]) + if m and m.group(1) not in AnnotationsUsed: + AnnotationsUsed[m.group(1)] = 1 + rerun = True + break + + OUTPUT = open(new_glossary, 'w', encoding='utf-8') + + OUTPUT.write('''%s + + Annotation Glossary +''' % MakeDocHeader("glossary")) + + for annotation in sorted(AnnotationsUsed.keys(), key=str.lower): + if annotation in AnnotationDefinition: + definition = AnnotationDefinition[annotation] + curletter = annotation[0].upper() + + if curletter != lastletter: + lastletter = curletter + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("%s\n" % curletter) + divopen = True + + OUTPUT.write(''' + %s + + %s + + +''' % (annotation, annotation, definition)) + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("\n") + OUTPUT.close() + + common.UpdateFileIfChanged(old_glossary, new_glossary, 0) + + +def OutputObjectTree(tree): + if not tree: + return + + # FIXME: use xml + old_tree_index = os.path.join(DB_OUTPUT_DIR, "tree_index.sgml") + new_tree_index = os.path.join(DB_OUTPUT_DIR, "tree_index.new") + + with open(new_tree_index, 'w', encoding='utf-8') as out: + out.write(MakeDocHeader("screen")) + out.write("\n\n") + out.write(AddTreeLineArt(tree)) + out.write("\n\n") + + common.UpdateFileIfChanged(old_tree_index, new_tree_index, 0) + + +def ReadKnownSymbols(file): + """Collect the names of non-private symbols from the $MODULE-sections.txt file. + + Args: + file: the $MODULE-sections.txt file + """ + + subsection = '' + + logging.info("Reading: %s", file) + INPUT = open(file, 'r', encoding='utf-8') + for line in INPUT: + if line.startswith('#'): + continue + + if line.startswith('
'): + subsection = '' + continue + + m = re.search(r'^', line, flags=re.I) + if m: + subsection = m.group(1) + continue + + if line.startswith(''): + continue + + if re.search(r'^(.*)<\/TITLE>', line): + continue + + m = re.search(r'^<FILE>(.*)<\/FILE>', line) + if m: + KnownSymbols[m.group(1) + ":long_description"] = 1 + KnownSymbols[m.group(1) + ":short_description"] = 1 + continue + + m = re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line) + if m: + continue + + m = re.search(r'^<\/SECTION>', line) + if m: + continue + + m = re.search(r'^(\S+)', line) + if m: + symbol = m.group(1) + if subsection != "Standard" and subsection != "Private": + KnownSymbols[symbol] = 1 + else: + KnownSymbols[symbol] = 0 + INPUT.close() + + +def OutputDeclaration(symbol, declaration): + """Returns the formatted documentation block for a symbol. + + Args: + symbol (str): the name of the function/macro/... + declaration (str): the declaration of the function/macro. + + Returns: + str: the formatted documentation + """ + + dtype = DeclarationTypes[symbol] + logging.info('Output Symbol: "%s" "%s"', symbol, dtype) + if dtype == 'MACRO': + return OutputMacro(symbol, declaration) + elif dtype == 'TYPEDEF': + return OutputTypedef(symbol, declaration) + elif dtype == 'STRUCT': + return OutputStruct(symbol, declaration) + elif dtype == 'ENUM': + return OutputEnum(symbol, declaration) + elif dtype == 'UNION': + return OutputUnion(symbol, declaration) + elif dtype == 'VARIABLE': + return OutputVariable(symbol, declaration) + elif dtype == 'FUNCTION': + return OutputFunction(symbol, declaration, dtype) + elif dtype == 'USER_FUNCTION': + return OutputFunction(symbol, declaration, dtype) + else: + logging.warning("Unknown symbol type %s for symbol %s", dtype, symbol) + return ('', '') + + +def OutputSymbolTraits(symbol): + """Returns the Since and StabilityLevel paragraphs for a symbol. + + Args: + symbol (str): the name to describe + + Returns: + str: paragraph or empty string + """ + + desc = '' + + if symbol in Since: + link_id = "api-index-" + Since[symbol] + desc += "<para role=\"since\">Since: <link linkend=\"%s\">%s</link></para>" % (link_id, Since[symbol]) + + if symbol in StabilityLevel: + stability = StabilityLevel[symbol] + if stability in AnnotationDefinition: + AnnotationsUsed[stability] = True + stability = "<acronym>%s</acronym>" % stability + desc += "<para role=\"stability\">Stability Level: %s</para>" % stability + return desc + + +def uri_escape(text): + if text is None: + return None + + # Build a char to hex map + escapes = {chr(i): ("%%%02X" % i) for i in range(256)} + + # Default unsafe characters. RFC 2732 ^(uric - reserved) + def do_escape(char): + return escapes[char] + return re.sub(r"([^A-Za-z0-9\-_.!~*'()]", do_escape, text) + + +def extract_struct_body(symbol, decl, has_typedef, public): + """Returns a normalized struct body. + + Normalizes whitespace and newlines and supresses non public members. + + Returns: + str: the nomalized struct declaration + """ + decl_out = '' + + m = re.search( + r'^\s*(typedef\s+)?struct\s*\w*\s*(?:\/\*.*\*\/)?\s*{(.*)}\s*\w*\s*;\s*$', decl, flags=re.DOTALL) + if m: + new_boby = '' + for line in m.group(2).splitlines(): + logging.info("Struct line: %s", line) + m2 = re.search(r'/\*\s*<\s*public\s*>\s*\*/', line) + m3 = re.search(r'/\*\s*<\s*(private|protected)\s*>\s*\*/', line) + if m2: + public = True + elif m3: + public = False + elif public: + new_boby += line + "\n" + + if new_boby: + # Strip any blank lines off the ends. + new_boby = re.sub(r'^\s*\n', '', new_boby) + new_boby = re.sub(r'\n\s*$', r'\n', new_boby) + + if has_typedef: + decl_out = "typedef struct {\n%s} %s;\n" % (new_boby, symbol) + else: + decl_out = "struct %s {\n%s};\n" % (symbol, new_boby) + else: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Couldn't parse struct:\n%s" % decl) + + if decl_out == '': + # If we couldn't parse the struct or it was all private, output an + # empty struct declaration. + if has_typedef: + decl_out = "typedef struct _%s %s;" % (symbol, symbol) + else: + decl_out = "struct %s;" % symbol + + return decl_out + + +def OutputSymbolExtraLinks(symbol): + """Returns extralinks for the symbol (if enabled). + + Args: + symbol (str): the name to describe + + Returns: + str: paragraph or empty string + """ + desc = '' + + if False: # NEW FEATURE: needs configurability + sstr = uri_escape(symbol) + mstr = uri_escape(MODULE) + desc += '''<ulink role="extralinks" url="http://www.google.com/codesearch?q=%s">code search</ulink> +<ulink role="extralinks" url="http://library.gnome.org/edit?module=%s&symbol=%s">edit documentation</ulink> +''' % (sstr, mstr, sstr) + + return desc + + +def OutputSectionExtraLinks(symbol, docsymbol): + desc = '' + + if False: # NEW FEATURE: needs configurability + sstr = uri_escape(symbol) + mstr = uri_escape(MODULE) + dsstr = uri_escape(docsymbol) + desc += '''<ulink role="extralinks" url="http://www.google.com/codesearch?q=%s">code search</ulink> +<ulink role="extralinks" url="http://library.gnome.org/edit?module=%s&symbol=%s">edit documentation</ulink> +''' % (sstr, mstr, dsstr) + return desc + + +def OutputMacro(symbol, declaration): + """Returns the synopsis and detailed description of a macro. + + Args: + symbol (str): the macro name. + declaration (str): the declaration of the macro. + + Returns: + str: the formatted docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + synop = "<row><entry role=\"define_keyword\">#define</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link>" % ( + sid, symbol) + + fields = common.ParseMacroDeclaration(declaration, CreateValidSGML) + title = symbol + if len(fields) > 0: + title += '()' + + desc = '<refsect2 id="%s" role="macro"%s>\n<title>%s\n' % (sid, condition, title) + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + if len(fields) > 0: + synop += "()" + + synop += "\n" + + # Don't output the macro definition if is is a conditional macro or it + # looks like a function, i.e. starts with "g_" or "_?gnome_", or it is + # longer than 2 lines, otherwise we get lots of complicated macros like + # g_assert. + if symbol not in DeclarationConditional and not symbol.startswith('g_') \ + and not re.search(r'^_?gnome_', symbol) and declaration.count('\n') < 2: + decl_out = CreateValidSGML(declaration) + desc += "%s\n" % decl_out + else: + desc += "" + "#define".ljust(RETURN_TYPE_FIELD_WIDTH) + symbol + m = re.search(r'^\s*#\s*define\s+\w+(\([^\)]*\))', declaration) + if m: + args = m.group(1) + pad = ' ' * (RETURN_TYPE_FIELD_WIDTH - len("#define ")) + # Align each line so that if should all line up OK. + args = args.replace('\n', '\n' + pad) + desc += CreateValidSGML(args) + + desc += "\n" + + desc += MakeDeprecationNote(symbol) + + parameters = OutputParamDescriptions("MACRO", symbol, fields) + + if symbol in SymbolDocs: + symbol_docs = ConvertMarkDown(symbol, SymbolDocs[symbol]) + desc += symbol_docs + + desc += parameters + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputTypedef(symbol, declaration): + """Returns the synopsis and detailed description of a typedef. + + Args: + symbol (str): the typedef. + declaration (str): the declaration of the typedef, + e.g. 'typedef unsigned int guint;' + + Returns: + str: the formatted docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + desc = "\n%s\n" % (sid, condition, symbol) + synop = "typedef%s\n" % ( + sid, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + if symbol not in DeclarationConditional: + decl_out = CreateValidSGML(declaration) + desc += "%s\n" % decl_out + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputStruct(symbol, declaration): + """Returns the synopsis and detailed description of a struct. + + We check if it is a object struct, and if so we only output parts of it that + are noted as public fields. We also use a different IDs for object structs, + since the original ID is used for the entire RefEntry. + + Args: + symbol (str): the struct. + declaration (str): the declaration of the struct. + + Returns: + str: the formatted docs + """ + is_gtype = False + default_to_public = True + if CheckIsObject(symbol): + logging.info("Found struct gtype: %s", symbol) + is_gtype = True + default_to_public = ObjectRoots[symbol] == 'GBoxed' + + sid = None + condition = None + if is_gtype: + sid = common.CreateValidSGMLID(symbol + "_struct") + condition = MakeConditionDescription(symbol + "_struct") + else: + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + # Determine if it is a simple struct or it also has a typedef. + has_typedef = False + if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration): + has_typedef = True + + type_output = None + desc = None + if has_typedef: + # For structs with typedefs we just output the struct name. + type_output = '' + desc = "\n%s\n" % (sid, condition, symbol) + else: + type_output = "struct" + desc = "\nstruct %s\n" % (sid, condition, symbol) + + synop = "%s%s\n" % ( + type_output, sid, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + # Form a pretty-printed, private-data-removed form of the declaration + + decl_out = '' + if re.search(r'^\s*$', declaration): + logging.info("Found opaque struct: %s", symbol) + decl_out = "typedef struct _%s %s;" % (symbol, symbol) + elif re.search(r'^\s*struct\s+\w+\s*;\s*$', declaration): + logging.info("Found opaque struct: %s", symbol) + decl_out = "struct %s;" % symbol + else: + decl_out = extract_struct_body(symbol, declaration, has_typedef, default_to_public) + + decl_out = CreateValidSGML(decl_out) + desc += "%s\n" % decl_out + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + # Create a table of fields and descriptions + + # FIXME: Inserting  's into the produced type declarations here would + # improve the output in most situations ... except for function + # members of structs! + def pfunc(*args): + return '%s' % (common.CreateValidSGMLID(sid + '.' + args[0]), args[0]) + fields = common.ParseStructDeclaration(declaration, not default_to_public, 0, MakeXRef, pfunc) + field_descrs, found = GetSymbolParams(symbol) + + if found: + missing_parameters = '' + unused_parameters = '' + sid = common.CreateValidSGMLID(symbol + ".members") + + desc += '''\nMembers + + + + + + +''' % sid + + for field_name, text in fields.items(): + param_annotations = '' + + desc += "%s\n" % text + if field_name in field_descrs: + field_descr, param_annotations = ExpandAnnotation(symbol, field_descrs[field_name]) + field_descr = ConvertMarkDown(symbol, field_descr) + # trim + field_descr = re.sub(r'^(\s|\n)+', '', field_descr, flags=re.M | re.S) + field_descr = re.sub(r'(\s|\n)+$', '', field_descr, flags=re.M | re.S) + desc += "%s\n%s\n" % ( + field_descr, param_annotations) + del field_descrs[field_name] + else: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Field description for %s::%s is missing in source code comment block." % (symbol, field_name)) + if missing_parameters != '': + missing_parameters += ", " + field_name + else: + missing_parameters = field_name + + desc += "\n" + + desc += "\n" + + desc += "\n\n" + for field_name in field_descrs: + # Documenting those standard fields is not required anymore, but + # we don't want to warn if they are documented anyway. + m = re.search(r'(g_iface|parent_instance|parent_class)', field_name) + if m: + continue + + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Field description for %s::%s is not used from source code comment block." % (symbol, field_name)) + if unused_parameters != '': + unused_parameters += ", " + field_name + else: + unused_parameters = field_name + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + else: + if fields: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Field descriptions for struct %s are missing in source code comment block." % symbol) + logging.info("Remaining structs fields: " + ':'.join(fields) + "\n") + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputUnion(symbol, declaration): + """Returns the synopsis and detailed description of a union. + + Args: + symbol (str): the union. + declaration (str): the declaration of the union. + + Returns: + str: the formatted docs + """ + is_gtype = False + if CheckIsObject(symbol): + logging.info("Found union gtype: %s", symbol) + is_gtype = True + + sid = None + condition = None + if is_gtype: + sid = common.CreateValidSGMLID(symbol + "_union") + condition = MakeConditionDescription(symbol + "_union") + else: + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + # Determine if it is a simple struct or it also has a typedef. + has_typedef = False + if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration): + has_typedef = True + + type_output = None + desc = None + if has_typedef: + # For unions with typedefs we just output the union name. + type_output = '' + desc = "\n%s\n" % (sid, condition, symbol) + else: + type_output = "union" + desc = "\nunion %s\n" % (sid, condition, symbol) + + synop = "%s%s\n" % ( + type_output, sid, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + # Create a table of fields and descriptions + + # FIXME: Inserting  's into the produced type declarations here would + # improve the output in most situations ... except for function + # members of structs! + def pfunc(*args): + return '%s' % (common.CreateValidSGMLID(sid + '.' + args[0]), args[0]) + fields = common.ParseStructDeclaration(declaration, 0, 0, MakeXRef, pfunc) + field_descrs, found = GetSymbolParams(symbol) + + logging.debug('Union %s has %d entries, found=%d, has_typedef=%d', symbol, len(fields), found, has_typedef) + + if found: + missing_parameters = '' + unused_parameters = '' + sid = common.CreateValidSGMLID('%s.members' % symbol) + + desc += '''\nMembers + + + + + + +''' % sid + + for field_name, text in fields.items(): + param_annotations = '' + + desc += "%s\n" % text + if field_name in field_descrs: + field_descr, param_annotations = ExpandAnnotation(symbol, field_descrs[field_name]) + field_descr = ConvertMarkDown(symbol, field_descr) + + # trim + field_descr = re.sub(r'^(\s|\n)+', '', field_descr, flags=re.M | re.S) + field_descr = re.sub(r'(\s|\n)+$', '', field_descr, flags=re.M | re.S) + desc += "%s\n%s\n" % ( + field_descr, param_annotations) + del field_descrs[field_name] + else: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Field description for %s::%s is missing in source code comment block." % (symbol, field_name)) + if missing_parameters != '': + missing_parameters += ", " + field_name + else: + missing_parameters = field_name + + desc += "\n" + + desc += "\n" + + desc += "\n" + for field_name in field_descrs: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Field description for %s::%s is not used from source code comment block." % (symbol, field_name)) + if unused_parameters != '': + unused_parameters += ", " + field_name + else: + unused_parameters = field_name + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + else: + if len(fields) > 0: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Field descriptions for union %s are missing in source code comment block." % symbol) + logging.info("Remaining union fields: " + ':'.join(fields) + "\n") + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputEnum(symbol, declaration): + """Returns the synopsis and detailed description of a enum. + + Args: + symbol (str): the enum. + declaration (str): the declaration of the enum. + + Returns: + str: the formatted docs + """ + is_gtype = False + if CheckIsObject(symbol): + logging.info("Found enum gtype: %s", symbol) + is_gtype = True + + sid = None + condition = None + if is_gtype: + sid = common.CreateValidSGMLID(symbol + "_enum") + condition = MakeConditionDescription(symbol + "_enum") + else: + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + synop = "enum%s\n" % ( + sid, symbol) + desc = "\nenum %s\n" % (sid, condition, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + # Create a table of fields and descriptions + + fields = common.ParseEnumDeclaration(declaration) + field_descrs, found = GetSymbolParams(symbol) + + missing_parameters = '' + unused_parameters = '' + + sid = common.CreateValidSGMLID("%s.members" % symbol) + desc += '''\nMembers + + + + + + +''' % sid + + for field_name in fields: + field_descr = field_descrs.get(field_name) + param_annotations = '' + + sid = common.CreateValidSGMLID(field_name) + condition = MakeConditionDescription(field_name) + desc += "%s\n" % ( + sid, field_name) + if field_descr: + field_descr, param_annotations = ExpandAnnotation(symbol, field_descr) + field_descr = ConvertMarkDown(symbol, field_descr) + desc += "%s\n%s\n" % ( + field_descr, param_annotations) + del field_descrs[field_name] + else: + if found: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Value description for %s::%s is missing in source code comment block." % (symbol, field_name)) + if missing_parameters != '': + missing_parameters += ", " + field_name + else: + missing_parameters = field_name + desc += "\n" + desc += "\n" + + desc += "\n" + for field_name in field_descrs: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Value description for %s::%s is not used from source code comment block." % (symbol, field_name)) + if unused_parameters != '': + unused_parameters += ", " + field_name + else: + unused_parameters = field_name + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + + if not found: + if len(fields) > 0: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Value descriptions for %s are missing in source code comment block." % symbol) + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputVariable(symbol, declaration): + """Returns the synopsis and detailed description of a variable. + + Args: + symbol (str): the extern'ed variable. + declaration (str): the declaration of the variable. + + Returns: + str: the formatted docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + logging.info("ouputing variable: '%s' '%s'", symbol, declaration) + + type_output = None + m1 = re.search( + r'^\s*extern\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*;', declaration) + m2 = re.search( + r'\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*=', declaration) + if m1: + mod1 = m1.group(1) or '' + ptr = m1.group(3) or '' + space = m1.group(4) or '' + mod2 = m1.group(5) or '' + type_output = "extern %s%s%s%s" % (mod1, ptr, space, mod2) + elif m2: + mod1 = m2.group(1) or '' + ptr = m2.group(3) or '' + space = m2.group(4) or '' + mod2 = m2.group(5) or '' + type_output = '%s%s%s%s' % (mod1, ptr, space, mod2) + else: + type_output = "extern" + + synop = "%s%s\n" % ( + type_output, sid, symbol) + + desc = "\n%s\n" % (sid, condition, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + decl_out = CreateValidSGML(declaration) + desc += "%s\n" % decl_out + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + param_desc, param_annotations = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + desc += "\n%s" % param_annotations + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputFunction(symbol, declaration, symbol_type): + """Returns the synopsis and detailed description of a function. + + Args: + symbol (str): the function. + declaration (str): the declaration of the function. + + Returns: + str: the formatted docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + # Take out the return type + # $1 $2 $3 + regex = r'\s*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)(\s*\**\s*(?:const|G_CONST_RETURN)?\s*\**\s*(?:restrict)?\s*)<\/RETURNS>\n' + m = re.search(regex, declaration) + declaration = re.sub(regex, '', declaration) + type_modifier = m.group(1) or '' + type = m.group(2) + pointer = m.group(3) + pointer = pointer.rstrip() + xref = MakeXRef(type, tagify(type, "returnvalue")) + start = '' + # if (symbol_type == 'USER_FUNCTION') + # start = "typedef " + # + + # We output const rather than G_CONST_RETURN. + type_modifier = re.sub(r'G_CONST_RETURN', 'const', type_modifier) + pointer = re.sub(r'G_CONST_RETURN', 'const', pointer) + pointer = re.sub(r'^\s+', ' ', pointer) + + ret_type_output = "%s%s%s%s\n" % (start, type_modifier, xref, pointer) + + indent_len = len(symbol) + 2 + char1 = char2 = char3 = '' + if symbol_type == 'USER_FUNCTION': + indent_len += 3 + char1 = "(" + char2 = "*" + char3 = ")" + + symbol_output = "%s%s%s%s" % (char1, sid, char2, symbol, char3) + if indent_len < MAX_SYMBOL_FIELD_WIDTH: + symbol_desc_output = "%s%s%s%s " % (char1, char2, symbol, char3) + else: + indent_len = MAX_SYMBOL_FIELD_WIDTH - 8 + symbol_desc_output = ('%s%s%s%s\n' % (char1, char2, symbol, char3)) + (' ' * (indent_len - 1)) + + synop = "%s%s ()\n" % ( + ret_type_output, symbol_output) + + desc = "\n%s ()\n" % (sid, condition, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + desc += "%s%s(" % (ret_type_output, symbol_desc_output) + + def tagfun(*args): + return tagify(args[0], "parameter") + + fields = common.ParseFunctionDeclaration(declaration, MakeXRef, tagfun) + + first = True + for field_name in fields.values(): + if first: + desc += field_name + first = False + else: + desc += ",\n" + (' ' * indent_len) + field_name + + desc += ");\n" + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + param_desc, param_annotations = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + desc += "\n%s" % param_annotations + + desc += OutputParamDescriptions("FUNCTION", symbol, fields.keys()) + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputParamDescriptions(symbol_type, symbol, fields): + """Returns the DocBook output describing the parameters of a symbol. + + This can be used for functions, macros or signal handlers. + + Args: + symbol_type (str): 'FUNCTION', 'MACRO' or 'SIGNAL'. Signal + handlers have an implicit user_data parameter last. + symbol (str): the name of the symbol being described. + fields (list): parsed fields from the declaration, used to determine + undocumented/unused entries + + Returns: + str: the formatted parameter docs + """ + output = '' + num_params = 0 + field_descrs = None + + if fields: + field_descrs = [f for f in fields if f not in ['void', 'Returns']] + else: + field_descrs = [] + + params = SymbolParams.get(symbol) + logging.info("param_desc(%s, %s) = %s", symbol_type, symbol, str(params)) + # This might be an empty dict, but for SIGNALS we append the user_data docs. + # TODO(ensonic): maybe create that docstring in GetSignals() + if params is not None: + returns = '' + params_desc = '' + missing_parameters = '' + unused_parameters = '' + + for param_name, param_desc in params.items(): + param_desc, param_annotations = ExpandAnnotation(symbol, param_desc) + param_desc = ConvertMarkDown(symbol, param_desc) + # trim + param_desc = re.sub(r'^(\s|\n)+', '', param_desc, flags=re.M | re.S) + param_desc = re.sub(r'(\s|\n)+$', '', param_desc, flags=re.M | re.S) + if param_name == "Returns": + returns = param_desc + if param_annotations != '': + returns += "\n%s" % param_annotations + + elif param_name == "void": + # FIXME: &common.LogWarning()? + logging.info("!!!! void in params for %s?\n", symbol) + else: + if fields: + if param_name not in field_descrs: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Parameter description for %s::%s is not used from source code comment block." % (symbol, param_name)) + if unused_parameters != '': + unused_parameters += ", " + param_name + else: + unused_parameters = param_name + else: + field_descrs.remove(param_name) + + if param_desc != '': + params_desc += "%s\n%s\n%s\n" % ( + param_name, param_desc, param_annotations) + num_params += 1 + + for param_name in field_descrs: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Parameter description for %s::%s is missing in source code comment block." % (symbol, param_name)) + if missing_parameters != '': + missing_parameters += ", " + param_name + else: + missing_parameters = param_name + + # Signals have an implicit user_data parameter which we describe. + if symbol_type == "SIGNAL": + params_desc += "user_data\nuser data set when the signal handler was connected.\n\n" + + # Start a table if we need one. + if params_desc != '': + sid = common.CreateValidSGMLID("%s.parameters" % symbol) + + output += '''\nParameters + + + + + + +''' % sid + output += params_desc + output += "\n" + + # Output the returns info last + if returns != '': + sid = common.CreateValidSGMLID("%s.returns" % symbol) + + output += '''\nReturns +''' % sid + output += returns + output += "\n" + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + + if num_params == 0 and fields and field_descrs: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + return output + + +def ParseStabilityLevel(stability, file, line, message): + """Parses a stability level and outputs a warning if it isn't valid. + Args: + stability (str): the stability text. + file, line: context for error message + message: description of where the level is from, to use in any error message. + Returns: + str: the parsed stability level string. + """ + stability = stability.strip() + sl = stability.strip().lower() + if sl == 'stable': + stability = "Stable" + elif sl == 'unstable': + stability = "Unstable" + elif sl == 'private': + stability = "Private" + else: + common.LogWarning(file, line, + "%s is %s. It should be one of these: Stable, " + "Unstable, or Private." % ( + message, stability)) + return str(stability) + + +def OutputDBFile(file, title, section_id, includes, functions_synop, other_synop, functions_details, other_desc, signals_synop, signals_desc, args_synop, args_desc, actions_synop, actions_desc, hierarchy, interfaces, implementations, prerequisites, derived, file_objects, default_stability): + """Outputs the final DocBook file for one section. + + Args: + file (str): the name of the file. + title (str): the title from the $MODULE-sections.txt file + section_id (str): the id to use for the toplevel tag. + includes (str): comma-separates list of include files added at top of + synopsis, with '<' '>' around them (if not already enclosed in ''). + functions_synop (str): the DocBook for the Functions Synopsis part. + other_synop (str): the DocBook for the Types and Values Synopsis part. + functions_details (str): the DocBook for the Functions Details part. + other_desc (str): the DocBook for the Types and Values Details part. + signal_synop (str): the DocBook for the Signal Synopsis part + signal_desc (str): the DocBook for the Signal Description part + args_synop (str): the DocBook for the Arg Synopsis part + args_desc (str): the DocBook for the Arg Description part + actions_synop (str): the DocBook for the Action Synopsis part + actions_desc (str): the DocBook for the Action Description part + hierarchy (str): the DocBook for the Object Hierarchy part + interfaces (str): the DocBook for the Interfaces part + implementations (str): the DocBook for the Known Implementations part + prerequisites (str): the DocBook for the Prerequisites part + derived (str): the DocBook for the Derived Interfaces part + file_objects (list): objects in this file + default_stability (str): fallback if no api-stability is set (optional) + + Returns: + bool: True if the docs where updated + """ + + logging.info("Output docbook for file %s with title '%s'", file, title) + + # The edited title overrides the one from the sections file. + new_title = SymbolDocs.get(file + ":title") + if new_title and not new_title.strip() == '': + title = new_title + logging.info("Found title: %s", title) + + short_desc = SymbolDocs.get(file + ":short_description") + if not short_desc or short_desc.strip() == '': + short_desc = '' + else: + # Don't use ConvertMarkDown here for now since we don't want blocks + short_desc = ExpandAbbreviations(title + ":short_description", short_desc) + logging.info("Found short_desc: %s", short_desc) + + long_desc = SymbolDocs.get(file + ":long_description") + if not long_desc or long_desc.strip() == '': + long_desc = '' + else: + long_desc = ConvertMarkDown(title + ":long_description", long_desc) + logging.info("Found long_desc: %s", long_desc) + + see_also = SymbolDocs.get(file + ":see_also") + if not see_also or re.search(r'^\s*()?\s*()?\s*$', see_also): + see_also = '' + else: + see_also = ConvertMarkDown(title + ":see_also", see_also) + logging.info("Found see_also: %s", see_also) + + if see_also: + see_also = "\nSee Also\n%s\n\n" % (section_id, see_also) + + stability = SymbolDocs.get(file + ":stability") + if not stability or re.search(r'^\s*$', stability): + stability = '' + else: + line_number = GetSymbolSourceLocation(file + ":stability")[1] + stability = ParseStabilityLevel(stability, file, line_number, "Section stability level") + logging.info("Found stability: %s", stability) + + if not stability: + stability = default_stability or '' + + if stability: + if stability in AnnotationDefinition: + AnnotationsUsed[stability] = True + stability = "%s" % stability + stability = "\nStability Level\n%s, unless otherwise indicated\n\n" % ( + section_id, stability) + + image = SymbolDocs.get(file + ":image") + if not image or re.search(r'^\s*$', image): + image = '' + else: + image = image.strip() + + format = None + + il = image.lower() + if re.search(r'jpe?g$', il): + format = "format='JPEG'" + elif il.endswith('png'): + format = "format='PNG'" + elif il.endswith('svg'): + format = "format='SVG'" + else: + format = '' + + image = " \n" % (image, format) + + include_output = '' + if includes: + include_output += "Includes" % section_id + for include in includes.split(','): + if re.search(r'^\".+\"$', include): + include_output += "#include %s\n" % include + else: + include = re.sub(r'^\s+|\s+$', '', include, flags=re.S) + include_output += "#include <%s>\n" % include + + include_output += "\n" + + extralinks = OutputSectionExtraLinks(title, "Section:%s" % file) + + old_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml') + new_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml.new') + + OUTPUT = open(new_db_file, 'w', encoding='utf-8') + + object_anchors = '' + for fobject in file_objects: + if fobject == section_id: + continue + sid = common.CreateValidSGMLID(fobject) + logging.info("Adding anchor for %s\n", fobject) + object_anchors += "" % sid + + # Make sure we produce valid docbook + if not functions_details: + functions_details = "" + + # We used to output this, but is messes up our common.UpdateFileIfChanged code + # since it changes every day (and it is only used in the man pages): + # "" + + OUTPUT.write(DB_REFENTRY.substitute({ + 'actions_desc': actions_desc, + 'actions_synop': actions_synop, + 'args_desc': args_desc, + 'args_synop': args_synop, + 'derived': derived, + 'extralinks': extralinks, + 'functions_details': functions_details, + 'functions_synop': functions_synop, + 'header': MakeDocHeader('refentry'), + 'hierarchy': hierarchy, + 'image': image, + 'include_output': include_output, + 'interfaces': interfaces, + 'implementations': implementations, + 'long_desc': long_desc, + 'object_anchors': object_anchors, + 'other_desc': other_desc, + 'other_synop': other_synop, + 'prerequisites': prerequisites, + 'section_id': section_id, + 'see_also': see_also, + 'signals_desc': signals_desc, + 'signals_synop': signals_synop, + 'short_desc': short_desc, + 'stability': stability, + 'title': title, + 'MODULE': MODULE.upper(), + })) + OUTPUT.close() + + return common.UpdateFileIfChanged(old_db_file, new_db_file, 0) + + +def OutputProgramDBFile(program, section_id): + """Outputs the final DocBook file for one program. + + Args: + file (str): the name of the file. + section_id (str): the id to use for the toplevel tag. + + Returns: + bool: True if the docs where updated + """ + logging.info("Output program docbook for %s", program) + + short_desc = SourceSymbolDocs.get(program + ":short_description") + if not short_desc or short_desc.strip() == '': + short_desc = '' + else: + # Don't use ConvertMarkDown here for now since we don't want blocks + short_desc = ExpandAbbreviations(program, short_desc) + logging.info("Found short_desc: %s", short_desc) + + synopsis = SourceSymbolDocs.get(program + ":synopsis") + if synopsis and synopsis.strip() != '': + items = synopsis.split(' ') + for i in range(0, len(items)): + parameter = items[i] + choice = "plain" + rep = '' + + # first parameter is the command name + if i == 0: + synopsis = "%s\n" % parameter + continue + + # square brackets indicate optional parameters, curly brackets + # indicate required parameters ("plain" parameters are also + # mandatory, but do not get extra decoration) + m1 = re.search(r'^\[(.+?)\]$', parameter) + m2 = re.search(r'^\{(.+?)\}$', parameter) + if m1: + choice = "opt" + parameter = m1.group(1) + elif m2: + choice = "req" + parameter = m2.group(1) + + # parameters ending in "..." are repeatable + if parameter.endswith('...'): + rep = ' rep=\"repeat\"' + parameter = parameter[:-3] + + # italic parameters are replaceable parameters + parameter = re.sub(r'\*(.+?)\*', r'\1', parameter) + + synopsis += "" % (choice, rep) + synopsis += parameter + synopsis += "\n" + + logging.info("Found synopsis: %s", synopsis) + else: + synopsis = "%s" % program + + long_desc = SourceSymbolDocs.get(program + ":long_description") + if not long_desc or long_desc.strip() == '': + long_desc = '' + else: + long_desc = ConvertMarkDown("%s:long_description" % program, long_desc) + logging.info("Found long_desc: %s", long_desc) + + options = '' + o = program + ":options" + if o in SourceSymbolDocs: + opts = SourceSymbolDocs[o].split('\t') + + logging.info('options: %d, %s', len(opts), str(opts)) + + options = "\nOptions\n\n" + for k in range(0, len(opts), 2): + opt_desc = opts[k + 1] + + opt_desc = re.sub(r'\*(.+?)\*', r'\1', opt_desc) + + options += "\n" + opt_names = opts[k].split(',') + for i in range(len(opt_names)): + prefix = ', ' if i > 0 else '' + # italic parameters are replaceable parameters + opt_name = re.sub(r'\*(.+?)\*', r'\1', opt_names[i]) + + options += "%s\n" % (prefix, opt_name) + + options += "\n" + options += "%s\n" % opt_desc + options += "\n" + + options += "\n" + + exit_status = SourceSymbolDocs.get(program + ":returns") + if exit_status and exit_status != '': + exit_status = ConvertMarkDown("%s:returns" % program, exit_status) + exit_status = "\nExit Status\n%s\n\n" % ( + section_id, exit_status) + else: + exit_status = '' + + see_also = SourceSymbolDocs.get(program + ":see_also") + if not see_also or re.search(r'^\s*()?\s*()?\s*$', see_also): + see_also = '' + else: + see_also = ConvertMarkDown("%s:see_also" % program, see_also) + logging.info("Found see_also: %s", see_also) + + if see_also: + see_also = "\nSee Also\n%s\n\n" % (section_id, see_also) + + old_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml") + new_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml.new") + + OUTPUT = open(new_db_file, 'w', encoding='utf-8') + + OUTPUT.write('''%s + + +%s +1 +User Commands + + +%s +%s + + +%s + + +Description +%s + +%s%s%s + +''' % (MakeDocHeader("refentry"), section_id, section_id, program, program, short_desc, synopsis, section_id, long_desc, options, exit_status, see_also)) + OUTPUT.close() + + return common.UpdateFileIfChanged(old_db_file, new_db_file, 0) + + +def OutputExtraFile(file): + """Copies an "extra" DocBook file into the output directory, expanding abbreviations. + + Args: + file (str): the source file. + + Returns: + bool: True if the docs where updated + """ + + basename = os.path.basename(file) + + old_db_file = os.path.join(DB_OUTPUT_DIR, basename) + new_db_file = os.path.join(DB_OUTPUT_DIR, basename + ".new") + + contents = open(file, 'r', encoding='utf-8').read() + + with open(new_db_file, 'w', encoding='utf-8') as out: + out.write(ExpandAbbreviations(basename + " file", contents)) + + return common.UpdateFileIfChanged(old_db_file, new_db_file, 0) + + +def GetDocbookHeader(main_file): + if os.path.exists(main_file): + INPUT = open(main_file, 'r', encoding='utf-8') + header = '' + for line in INPUT: + if re.search(r'^\s*<(book|chapter|article)', line): + # check that the top-level tagSYSTEM or the doctype decl contain the xinclude namespace decl + if not re.search(r'http:\/\/www.w3.org\/200[13]\/XInclude', line) and \ + not re.search(r'http:\/\/www.w3.org\/200[13]\/XInclude', header, flags=re.MULTILINE): + header = '' + break + + # if there are SYSTEM ENTITIES here, we should prepend "../" to the path + # FIXME: not sure if we can do this now, as people already work-around the problem + # r'#', r''; + line = re.sub( + r'', r'', line) + header += line + INPUT.close() + header = header.strip() + else: + header = ''' + + + %gtkdocentities; +]>''' + return header + + +def OutputBook(main_file, book_top, book_bottom, obj_tree): + """Outputs the entities that need to be included into the main docbook file for the module. + + Args: + book_top (str): the declarations of the entities, which are added + at the top of the main docbook file. + book_bottom (str): the entities, which are added in the main docbook + file at the desired position. + obj_tree (list): object tree list + """ + + old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top") + new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top.new") + + with open(new_file, 'w', encoding='utf-8') as out: + out.write(book_top) + + common.UpdateFileIfChanged(old_file, new_file, 0) + + old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom") + new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom.new") + + with open(new_file, 'w', encoding='utf-8') as out: + out.write(book_bottom) + + common.UpdateFileIfChanged(old_file, new_file, 0) + + # If the main docbook file hasn't been created yet, we create it here. + # The user can tweak it later. + if main_file and not os.path.exists(main_file): + OUTPUT = open(main_file, 'w', encoding='utf-8') + + logging.info("no master doc, create default one at: " + main_file) + + OUTPUT.write('''%s + + + &package_name; Reference Manual + + for &package_string;. + The latest version of this documentation can be found on-line at + http://[SERVER]/&package_name;/. + + + + + [Insert title here] +%s +''' % (MakeDocHeader("book"), book_bottom)) + if obj_tree: + OUTPUT.write(''' + Object Hierarchy + + +''') + else: + OUTPUT.write(''' +''') + + OUTPUT.write(''' + API Index + + + + Index of deprecated API + + +''') + for version in sorted(set(Since.values())): + dash_version = version.replace('.', '-') + OUTPUT.write(''' + Index of new API in %s + + +''' % (dash_version, version, version, version)) + + if AnnotationsUsed: + OUTPUT.write(''' +''') + else: + OUTPUT.write(''' +''') + + OUTPUT.write(''' +''') + + OUTPUT.close() + + +def CreateValidSGML(text): + """Turn any chars which are used in XML into entities. + + e.g. '<' into '<' + + Args: + text (str): the text to turn into proper XML. + + Returns: + str: escaped input + """ + + text = text.replace('&', '&') # Do this first, or the others get messed up. + text = text.replace('<', '<') + text = text.replace('>', '>') + # browsers render single tabs inconsistently + text = re.sub(r'([^\s])\t([^\s])', r'\1 \2', text) + return text + + +def ConvertXMLChars(symbol, text): + """Escape XML chars. + + This is used for text in source code comment blocks, to turn + chars which are used in XML into entities, e.g. '<' into + <'. Depending on INLINE_MARKUP_MODE, this is done + unconditionally or only if the character doesn't seem to be + part of an XML construct (tag or entity reference). + Args: + text (str): the text to turn into proper XML. + + Returns: + str: escaped input + """ + + if INLINE_MARKUP_MODE: + # For the XML mode only convert to entities outside CDATA sections. + return ModifyXMLElements(text, symbol, + "]*>", + ConvertXMLCharsEndTag, + ConvertXMLCharsCallback) + # For the simple non-sgml mode, convert to entities everywhere. + + text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up. + # Allow '<' in verbatim markdown + # TODO: we don't want to convert any of them between `` + text = re.sub(r'(?' at beginning of string for blockquote markdown + text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text) + + return text + + +def ConvertXMLCharsEndTag(start_tag): + if start_tag == '" + return "" + + +def ConvertXMLCharsCallback(text, symbol, tag): + if re.search(r'^ specially here. + return ModifyXMLElements(text, symbol, + "' at beginning of string for blockquote markdown + text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text) + + # Handle "#include " + text = re.sub(r'#include(\s+)<([^>]+)>', r'#include\1<\2>', text) + + return text + + +def ConvertXMLCharsCallback2(text, symbol, tag): + # If we're not in CDATA convert to entities. + # We could handle differently, though I'm not sure it helps. + if tag == '': + # replace only if its not a tag + text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up. + text = re.sub(r'<(?![a-zA-Z\/!])', r'<', text) + text = re.sub(r'''(?''', r'>', text) + # Handle "#include " + text = re.sub(r'/#include(\s+)<([^>]+)>', r'#include\1<\2>', text) + + return text + + +def ExpandAnnotation(symbol, param_desc): + """This turns annotations into acronym tags. + Args: + symbol (str): the symbol being documented, for error messages. + param_desc (str): the text to expand. + + Returns: + str: the remaining param_desc + str: the formatted annotations + """ + param_annotations = '' + + # look for annotations at the start of the comment part + # function level annotations don't end with a colon ':' + m = re.search(r'^\s*\((.*?)\)(:|$)', param_desc) + if m: + param_desc = param_desc[m.end():] + + annotations = re.split(r'\)\s*\(', m.group(1)) + logging.info("annotations for %s: '%s'\n", symbol, m.group(1)) + for annotation in annotations: + # need to search for the longest key-match in %AnnotationDefinition + match_length = 0 + match_annotation = '' + + for annotationdef in AnnotationDefinition: + if annotation.startswith(annotationdef): + if len(annotationdef) > match_length: + match_length = len(annotationdef) + match_annotation = annotationdef + + annotation_extra = '' + if match_annotation != '': + m = re.search(match_annotation + r'\s+(.*)', annotation) + if m: + annotation_extra = " " + m.group(1) + + AnnotationsUsed[match_annotation] = 1 + param_annotations += "[%s%s]" % (match_annotation, annotation_extra) + else: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "unknown annotation \"%s\" in documentation for %s." % (annotation, symbol)) + param_annotations += "[%s]" % annotation + + param_desc = param_desc.strip() + m = re.search(r'^(.*?)\.*\s*$', param_desc, flags=re.S) + param_desc = m.group(1) + '. ' + + if param_annotations != '': + param_annotations = "%s" % param_annotations + + return (param_desc, param_annotations) + + +def ExpandAbbreviations(symbol, text): + """Expand the shortcut notation for symbol references. + + This turns the abbreviations function(), macro(), @param, %constant, and #symbol + into appropriate DocBook markup. CDATA sections and parts + are skipped. + + Args: + symbol (str): the symbol being documented, for error messages. + text (str): the text to expand. + + Returns: + str: the expanded text + """ + # Note: This is a fallback and normally done in the markdown parser + + logging.debug('expand abbreviations for "%s", text: [%s]', symbol, text) + m = re.search(r'\|\[[^\n]*\n(.*)\]\|', text, flags=re.M | re.S) + if m: + logging.debug('replaced entities in code block') + text = text[:m.start(1)] + md_to_db.ReplaceEntities(m.group(1)) + text[m.end(1):] + + # Convert "|[" and "]|" into the start and end of program listing examples. + # Support \[ modifiers + text = re.sub(r'\|\[', + r'', text) + + # keep CDATA unmodified, preserve ulink tags (ideally we preseve all tags + # as such) + return ModifyXMLElements(text, symbol, + "]*>|]*>|" + if start_tag == "' + m = re.search(r'<(\w+)', start_tag) + if m: + return "" % m.group(1) + + logging.warning('no end tag for "%s"', start_tag) + return '' + + +def ExpandAbbreviationsCallback(text, symbol, tag): + # Called inside or outside each CDATA or section. + if tag.startswith(r'^ sections, so we expand + # any gtk-doc abbreviations. + + # Convert '@param()' + # FIXME: we could make those also links ($symbol.$2), but that would be less + # useful as the link target is a few lines up or down + text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)', r'\1\2()', text) + + # Convert 'function()' or 'macro()'. + # if there is abc_*_def() we don't want to make a link to _def() + # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/ + def f1(m): + return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2) + "()", "function")) + text = re.sub(r'([^\*.\w])(\w+)\s*\(\)', f1, text) + # handle #Object.func() + text = re.sub(r'(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)', f1, text) + + # Convert '@param', but not '\@param'. + text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)', r'\1\2', text) + text = re.sub(r'/\\\@', r'\@', text) + + # Convert '%constant', but not '\%constant'. + # Also allow negative numbers, e.g. %-1. + def f2(m): + return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2), "literal")) + text = re.sub(r'(\A|[^\\])\%(-?\w+)', f2, text) + text = re.sub(r'\\\%', r'\%', text) + + # Convert '#symbol', but not '\#symbol'. + def f3(m): + return m.group(1) + MakeHashXRef(m.group(2), "type") + text = re.sub(r'(\A|[^\\])#([\w\-:\.]+[\w]+)', f3, text) + text = re.sub(r'\\#', '#', text) + + return text + + +def ExpandAbbreviationsCallback2(text, symbol, tag): + # This is called inside a + if tag == '': + # We are inside a but outside any CDATA sections, + # so we expand any gtk-doc abbreviations. + # FIXME: why is this different from &ExpandAbbreviationsCallback(), + # why not just call it + text = re.sub(r'#(\w+)', lambda m: '%s;' % MakeHashXRef(m.group(1), ''), text) + elif tag == ". + + Args: + text (str): the text. + symbol (str): the symbol currently being documented (only used for + error messages). + start_tag_regexp (str): the regular expression to match start tags. + e.g. "]*>" to + match CDATA sections or programlisting elements. + end_tag_func (func): function which is passed the matched start tag + and should return the appropriate end tag string + regexp. + callback - callback called with each part of the text. It is + called with a piece of text, the symbol being + documented, and the matched start tag or '' if the text + is outside the XML elements being matched. + + Returns: + str: modified text + """ + before_tag = start_tag = end_tag_regexp = end_tag = None + result = '' + + logging.debug('modify xml for symbol: %s, regex: %s, text: [%s]', symbol, start_tag_regexp, text) + + m = re.search(start_tag_regexp, text, flags=re.S) + while m: + before_tag = text[:m.start()] # Prematch for last successful match string + start_tag = m.group(0) # Last successful match + text = text[m.end():] # Postmatch for last successful match string + # get the matching end-tag for current tag + end_tag_regexp = end_tag_func(start_tag) + + logging.debug('symbol: %s matched start: %s, end_tag: %s, text: [%s]', symbol, start_tag, end_tag_regexp, text) + + logging.debug('converting before tag: [%s]', before_tag) + result += callback(before_tag, symbol, '') + result += start_tag + + m2 = re.search(end_tag_regexp, text, flags=re.S) + if m2: + before_tag = text[:m2.start()] + end_tag = m2.group(0) + text = text[m2.end():] + + logging.debug('symbol: %s matched end %s: text: [%s]', symbol, end_tag, text) + + result += callback(before_tag, symbol, start_tag) + result += end_tag + else: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Can't find tag end: %s in docs for: %s." % (end_tag_regexp, symbol)) + # Just assume it is all inside the tag. + result += callback(text, symbol, start_tag) + text = '' + m = re.search(start_tag_regexp, text, flags=re.S) + + # Handle any remaining text outside the tags. + logging.debug('converting after tag: [%s]', text) + result += callback(text, symbol, '') + logging.debug('results for symbol: %s, text: [%s]', symbol, result) + + return result + + +def tagify(text, elem): + # Adds a tag around some text. + # e.g tagify("Text", "literal") => "Text". + return '<' + elem + '>' + text + '' + + +def MakeDocHeader(tag): + """Builds a docbook header for the given tag. + + Args: + tag (str): doctype tag + + Returns: + str: the docbook header + """ + header = re.sub(r'', r'', header) + return header + + +def MakeXRef(symbol, text=None): + """This returns a cross-reference link to the given symbol. + + Though it doesn't try to do this for a few standard C types that it knows + won't be in the documentation. + + Args: + symbol (str): the symbol to try to create a XRef to. + text (str): text to put inside the XRef, defaults to symbol + + Returns: + str: a docbook link + """ + symbol = symbol.strip() + if not text: + text = symbol + + # Get rid of special suffixes ('-struct','-enum'). + text = re.sub(r'-struct$', '', text) + text = re.sub(r'-enum$', '', text) + + if ' ' in symbol: + return text + + logging.info("Getting type link for %s -> %s", symbol, text) + + symbol_id = common.CreateValidSGMLID(symbol) + return "%s" % (symbol_id, text) + + +def MakeIndexterms(symbol, sid): + """This returns a indexterm elements for the given symbol + + Args: + symbol (str): the symbol to create indexterms for + + Returns: + str: doxbook index terms + """ + terms = '' + sortas = '' + + # make the index useful, by omitting the namespace when sorting + if NAME_SPACE != '': + m = re.search(r'^%s\_?(.*)' % NAME_SPACE, symbol, flags=re.I) + if m: + sortas = ' sortas="%s"' % m.group(1) + + if symbol in Deprecated: + terms += "%s" % ( + sid, sortas, symbol) + IndexEntriesDeprecated[symbol] = sid + IndexEntriesFull[symbol] = sid + if symbol in Since: + since = Since[symbol].strip() + if since != '': + terms += "%s" % ( + sid, since, sortas, symbol) + IndexEntriesSince[symbol] = sid + IndexEntriesFull[symbol] = sid + if terms == '': + terms += "%s" % (sid, sortas, symbol) + IndexEntriesFull[symbol] = sid + return terms + + +def MakeDeprecationNote(symbol): + """This returns a deprecation warning for the given symbol. + + Args: + symbol (str): the symbol to try to create a warning for. + + Returns: + str: formatted warning or empty string if symbol is not deprecated + """ + desc = '' + if symbol in Deprecated: + desc += "%s " % symbol + note = Deprecated[symbol] + + m = re.search(r'^\s*([0-9\.]+)\s*:?', note) + if m: + desc += "has been deprecated since version %s and should not be used in newly-written code." % m.group( + 1) + else: + desc += "is deprecated and should not be used in newly-written code." + + note = re.sub(r'^\s*([0-9\.]+)\s*:?\s*', '', note) + note = note.strip() + + if note != '': + note = ConvertMarkDown(symbol, note) + desc += " " + note + + desc += "\n" + + return desc + + +def MakeConditionDescription(symbol): + """This returns a summary of conditions for the given symbol. + + Args: + symbol (str): the symbol to create the summary for. + + Returns: + str: formatted text or empty string if no special conditions apply. + """ + desc = '' + if symbol in Deprecated: + if desc != '': + desc += "|" + m = re.search(r'^\s*(.*?)\s*$', Deprecated[symbol]) + if m: + desc += "deprecated:%s" % m.group(1) + else: + desc += "deprecated" + + if symbol in Since: + if desc != '': + desc += "|" + m = re.search(r'^\s*(.*?)\s*$', Since[symbol]) + if m: + desc += "since:%s" % m.group(1) + else: + desc += "since" + + if symbol in StabilityLevel: + if desc != '': + desc += "|" + + desc += "stability:" + StabilityLevel[symbol] + + if desc != '': + cond = re.sub(r'"', r'"', desc) + desc = ' condition=\"%s\"' % cond + logging.info("condition for '%s' = '%s'", symbol, desc) + + return desc + + +def GetHierarchy(gobject, hierarchy): + """Generate the object inheritance graph. + + Returns the DocBook output describing the ancestors and + immediate children of a GObject subclass. It uses the + global Objects and ObjectLevels arrays to walk the tree. + + Args: + object (str): the GtkObject subclass. + hierarchy (list) - previous hierarchy + + Returns: + list: lines of docbook describing the hierarchy + """ + # Find object in the objects array. + found = False + children = [] + level = 0 + j = 0 + for i in range(len(Objects)): + if found: + if ObjectLevels[i] <= level: + break + + elif ObjectLevels[i] == level + 1: + children.append(Objects[i]) + + elif Objects[i] == gobject: + found = True + j = i + level = ObjectLevels[i] + + if not found: + return hierarchy + + logging.info("=== Hierarchy for: %s (%d existing entries) ===", gobject, len(hierarchy)) + + # Walk up the hierarchy, pushing ancestors onto the ancestors array. + ancestors = [gobject] + logging.info("Level: %s", level) + while level > 1: + j -= 1 + if ObjectLevels[j] < level: + ancestors.append(Objects[j]) + level = ObjectLevels[j] + logging.info("Level: %s", level) + + # Output the ancestors, indented and with links. + logging.info('%d ancestors', len(ancestors)) + last_index = 0 + level = 1 + for i in range(len(ancestors) - 1, -1, -1): + ancestor = ancestors[i] + ancestor_id = common.CreateValidSGMLID(ancestor) + indent = ' ' * (level * 4) + # Don't add a link to the current object, i.e. when i == 0. + if i > 0: + entry_text = indent + "%s" % (ancestor_id, ancestor) + alt_text = indent + ancestor + else: + entry_text = indent + ancestor + alt_text = indent + "%s" % (ancestor_id, ancestor) + + logging.info("Checking for '%s' or '%s'", entry_text, alt_text) + # Check if we already have this object + index = -1 + for j in range(len(hierarchy)): + if hierarchy[j] == entry_text or (hierarchy[j] == alt_text): + index = j + break + if index == -1: + # We have a new entry, find insert position in alphabetical order + found = False + for j in range(last_index, len(hierarchy)): + if not re.search(r'^' + indent, hierarchy[j]): + last_index = j + found = True + break + elif re.search(r'^%s[^ ]' % indent, hierarchy[j]): + stripped_text = hierarchy[j] + if r'', '', stripped_text) + stripped_text = re.sub(r'', '', stripped_text) + + if entry_text < stripped_text: + last_index = j + found = True + break + + # Append to bottom + if not found: + last_index = len(hierarchy) + + logging.debug('insert at %d: %s', last_index, entry_text) + hierarchy.insert(last_index, entry_text) + last_index += 1 + else: + # Already have this one, make sure we use the not linked version + if r'%s" % (sid, children[i]) + logging.debug('insert at %d: %s', last_index, indented_text) + hierarchy.insert(last_index, indented_text) + last_index += 1 + return hierarchy + + +def GetInterfaces(gobject): + """Generate interface implementation graph. + + Returns the DocBook output describing the interfaces + implemented by a class. It uses the global Interfaces hash. + + Args: + object (str): the GObject subclass. + + Returns: + str: implemented interfaces + """ + text = '' + # Find object in the objects array. + if gobject in Interfaces: + ifaces = Interfaces[gobject].split() + text = ''' +%s implements +''' % gobject + count = len(ifaces) + for i in range(count): + sid = common.CreateValidSGMLID(ifaces[i]) + text += " %s" % (sid, ifaces[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetImplementations(gobject): + """Generate interface usage graph. + + Returns the DocBook output describing the implementations + of an interface. It uses the global Interfaces hash. + + Args: + object (str): the GObject subclass. + + Returns: + str: interface implementations + """ + text = '' + impls = [] + for key in Interfaces: + if re.search(r'\b%s\b' % gobject, Interfaces[key]): + impls.append(key) + + count = len(impls) + if count > 0: + impls.sort() + text = ''' +%s is implemented by +''' % gobject + for i in range(count): + sid = common.CreateValidSGMLID(impls[i]) + text += " %s" % (sid, impls[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetPrerequisites(iface): + """Generates interface requirements. + + Returns the DocBook output describing the prerequisites + of an interface. It uses the global Prerequisites hash. + Args: + iface (str): the interface. + + Returns: + str: required interfaces + """ + + text = '' + if iface in Prerequisites: + text = ''' +%s requires +''' % iface + prereqs = Prerequisites[iface].split() + count = len(prereqs) + for i in range(count): + sid = common.CreateValidSGMLID(prereqs[i]) + text += " %s" % (sid, prereqs[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetDerived(iface): + """ + Returns the DocBook output describing the derived interfaces + of an interface. It uses the global %Prerequisites hash. + + Args: + iface (str): the interface. + + Returns: + str: derived interfaces + """ + text = '' + derived = [] + for key in Prerequisites: + if re.search(r'\b%s\b' % iface, Prerequisites[key]): + derived.append(key) + + count = len(derived) + if count > 0: + derived.sort() + text = ''' +%s is required by +''' % iface + for i in range(count): + sid = common.CreateValidSGMLID(derived[i]) + text += " %s" % (sid, derived[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetSignals(gobject): + """Generate signal docs. + + Returns the synopsis and detailed description DocBook output + for the signal handlers of a given GObject subclass. + + Args: + object (str): the GObject subclass, e.g. 'GtkButton'. + + Returns: + str: signal docs + """ + synop = '' + desc = '' + + for i in range(len(SignalObjects)): + if SignalObjects[i] == gobject: + logging.info("Found signal: %s", SignalNames[i]) + name = SignalNames[i] + symbol = '%s::%s' % (gobject, name) + sid = common.CreateValidSGMLID('%s-%s' % (gobject, name)) + + desc += u"The <literal>“%s”</literal> signal\n" % ( + sid, name) + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + desc += "" + + m = re.search(r'\s*(const\s+)?(\w+)\s*(\**)', SignalReturns[i]) + type_modifier = m.group(1) or '' + gtype = m.group(2) + pointer = m.group(3) + xref = MakeXRef(gtype, tagify(gtype, "returnvalue")) + + ret_type_output = '%s%s%s' % (type_modifier, xref, pointer) + callback_name = "user_function" + desc += '%s\n%s (' % (ret_type_output, callback_name) + + indentation = ' ' * (len(callback_name) + 2) + + sourceparams = SourceSymbolParams.get(symbol) + sourceparam_names = None + if sourceparams: + sourceparam_names = list(sourceparams) # keys as list + params = SignalPrototypes[i].splitlines() + type_len = len("gpointer") + name_len = len("user_data") + # do two passes, the first one is to calculate padding + for l in range(2): + for j in range(len(params)): + param_name = None + # allow alphanumerics, '_', '[' & ']' in param names + m = re.search(r'^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$', params[j]) + if m: + gtype = m.group(1) + pointer = m.group(2) + if sourceparam_names: + if j < len(sourceparam_names): + param_name = sourceparam_names[j] + logging.info('from sourceparams: "%s" (%d: %s)', param_name, j, params[j]) + # we're missing the docs for this param, don't warn here though + else: + param_name = m.group(3) + logging.info('from params: "%s" (%d: %s)', param_name, j, params[j]) + + if not param_name: + param_name = "arg%d" % j + + if l == 0: + if len(gtype) + len(pointer) > type_len: + type_len = len(gtype) + len(pointer) + if len(param_name) > name_len: + name_len = len(param_name) + else: + logging.info("signal arg[%d]: '%s'", j, param_name) + xref = MakeXRef(gtype, tagify(gtype, "type")) + pad = ' ' * (type_len - len(gtype) - len(pointer)) + desc += '%s%s %s%s,\n' % (xref, pad, pointer, param_name) + desc += indentation + + else: + common.LogWarning(*GetSymbolSourceLocation(symbol), + "Can't parse arg: %s\nArgs:%s" % (params[j], SignalPrototypes[i])) + + xref = MakeXRef("gpointer", tagify("gpointer", "type")) + pad = ' ' * (type_len - len("gpointer")) + desc += '%s%s user_data)' % (xref, pad) + desc += "\n" + + flags = SignalFlags[i] + flags_string = '' + if flags: + if 'f' in flags: + flags_string = "Run First" + + elif 'l' in flags: + flags_string = "Run Last" + + elif 'c' in flags: + flags_string = "Cleanup" + flags_string = "Cleanup" + + if 'r' in flags: + if flags_string: + flags_string += " / " + flags_string = "No Recursion" + + if 'd' in flags: + if flags_string: + flags_string += " / " + flags_string = "Has Details" + + if 'a' in flags: + if flags_string: + flags_string += " / " + flags_string = "Action" + + if 'h' in flags: + if flags_string: + flags_string += " / " + flags_string = "No Hooks" + + synop += "%s%s%s\n" % ( + ret_type_output, sid, name, flags_string) + + parameters = OutputParamDescriptions("SIGNAL", symbol, None) + logging.info("formatted signal params: '%s' -> '%s'", symbol, parameters) + + AllSymbols[symbol] = 1 + if symbol in SymbolDocs: + symbol_docs = ConvertMarkDown(symbol, SymbolDocs[symbol]) + + desc += symbol_docs + + if not IsEmptyDoc(SymbolDocs[symbol]): + AllDocumentedSymbols[symbol] = 1 + + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + param_desc, param_annotations = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + desc += "\n%s" % param_annotations + + desc += MakeDeprecationNote(symbol) + + desc += parameters + if flags_string: + desc += "Flags: %s\n" % flags_string + + desc += OutputSymbolTraits(symbol) + desc += "" + + return (synop, desc) + + +def GetArgs(gobject): + """Generate property docs. + + Returns the synopsis and detailed description DocBook output + for the Args of a given GtkObject subclass. + + Args: + object (str): the GObject subclass, e.g. 'GtkButton'. + + Returns: + str: property docs + """ + synop = '' + desc = '' + child_synop = '' + child_desc = '' + style_synop = '' + style_desc = '' + + for i in range(len(ArgObjects)): + if ArgObjects[i] == gobject: + logging.info("Found arg: %s", ArgNames[i]) + name = ArgNames[i] + flags = ArgFlags[i] + flags_string = '' + kind = '' + id_sep = '' + + if 'c' in flags: + kind = "child property" + id_sep = "c-" + elif 's' in flags: + kind = "style property" + id_sep = "s-" + else: + kind = "property" + + # Remember only one colon so we don't clash with signals. + symbol = '%s:%s' % (gobject, name) + # use two dashes and ev. an extra separator here for the same reason. + sid = common.CreateValidSGMLID('%s--%s%s' % (gobject, id_sep, name)) + + atype = ArgTypes[i] + type_output = None + arange = ArgRanges[i] + range_output = CreateValidSGML(arange) + default = ArgDefaults[i] + default_output = CreateValidSGML(default) + + if atype == "GtkString": + atype = "char *" + + if atype == "GtkSignal": + atype = "GtkSignalFunc, gpointer" + type_output = MakeXRef("GtkSignalFunc") + ", " + MakeXRef("gpointer") + elif re.search(r'^(\w+)\*$', atype): + m = re.search(r'^(\w+)\*$', atype) + type_output = MakeXRef(m.group(1), tagify(m.group(1), "type")) + " *" + else: + type_output = MakeXRef(atype, tagify(atype, "type")) + + if 'r' in flags: + flags_string = "Read" + + if 'w' in flags: + if flags_string: + flags_string += " / " + flags_string += "Write" + + if 'x' in flags: + if flags_string: + flags_string += " / " + flags_string += "Construct" + + if 'X' in flags: + if flags_string: + flags_string += " / " + flags_string += "Construct Only" + + AllSymbols[symbol] = 1 + blurb = '' + if symbol in SymbolDocs and not IsEmptyDoc(SymbolDocs[symbol]): + blurb = ConvertMarkDown(symbol, SymbolDocs[symbol]) + logging.info(".. [%s][%s]", SymbolDocs[symbol], blurb) + AllDocumentedSymbols[symbol] = 1 + + else: + if ArgBlurbs[i] != '': + blurb = "" + CreateValidSGML(ArgBlurbs[i]) + "" + AllDocumentedSymbols[symbol] = 1 + else: + # FIXME: print a warning? + logging.info(".. no description") + + pad1 = '' + if len(name) < 24: + pad1 = " " * (24 - len(name)) + + arg_synop = "%s%s%s\n" % ( + type_output, sid, name, flags_string) + arg_desc = u"The <literal>“%s”</literal> %s\n" % ( + sid, name, kind) + arg_desc += MakeIndexterms(symbol, sid) + arg_desc += "\n" + arg_desc += OutputSymbolExtraLinks(symbol) + + arg_desc += u" “%s”%s %s\n" % (name, pad1, type_output) + arg_desc += blurb + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + param_desc, param_annotations = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + arg_desc += "\n%s" % param_annotations + + arg_desc += MakeDeprecationNote(symbol) + + arg_desc += "Owner: %s\n" % gobject + + if flags_string: + arg_desc += "Flags: %s\n" % flags_string + + if arange != '': + arg_desc += "Allowed values: %s\n" % range_output + + if default != '': + arg_desc += "Default value: %s\n" % default_output + + arg_desc += OutputSymbolTraits(symbol) + arg_desc += "\n" + + if 'c' in flags: + child_synop += arg_synop + child_desc += arg_desc + + elif 's' in flags: + style_synop += arg_synop + style_desc += arg_desc + + else: + synop += arg_synop + desc += arg_desc + + return (synop, child_synop, style_synop, desc, child_desc, style_desc) + + +def GetActions(gobject): + """Generate action docs. + + Returns the synopsis and detailed description DocBook output + for the actions of a given GtkWidget subclass. + + Args: + object (str): the GObject subclass, e.g. 'GtkButton'. + + Returns: + str: action docs + """ + synop = '' + desc = '' + + for i in range(len(ActionObjects)): + if ActionObjects[i] == gobject: + logging.info("Found action: %s", ActionNames[i]) + name = ActionNames[i] + params = ActionParams[i] + prop = ActionProperties[i] + + # Remember: pipe, so we don't clash with signals. + symbol = '%s|%s' % (gobject, name) + sid = common.CreateValidSGMLID(symbol) + + AllSymbols[symbol] = 1 + blurb = '' + if symbol in SymbolDocs and not IsEmptyDoc(SymbolDocs[symbol]): + blurb = ConvertMarkDown(symbol, SymbolDocs[symbol]) + logging.info(".. [%s][%s]", SymbolDocs[symbol], blurb) + AllDocumentedSymbols[symbol] = 1 + + else: + # FIXME: print a warning? + logging.info(".. no description") + + pad1 = '' + if len(name) < 24: + pad1 = " " * (24 - len(name)) + + action_synop = "%s%s\n" % ( + sid, name, params) + action_desc = u"The <literal>“%s”</literal> action\n" % ( + sid, name) + action_desc += MakeIndexterms(symbol, sid) + action_desc += "\n" + action_desc += OutputSymbolExtraLinks(symbol) + if blurb != '': + action_desc += blurb + elif prop != '': + action_desc += "The %s action sets the %s property.\n" % (name, MakeHashXRef (gobject + ':' + prop, "type")) + action_desc += MakeDeprecationNote(symbol) + + if params != '': + action_desc += "Parameter type: %s\n" % params + + action_desc += OutputParamDescriptions("ACTION", symbol, None) + action_desc += OutputSymbolTraits(symbol) + action_desc += "\n" + + synop += action_synop + desc += action_desc + + return (synop, desc) + +def IgnorePath(path, source_dirs, ignore_files): + for sdir in source_dirs: + # Cut off base directory + m1 = re.search(r'^%s/(.*)$' % re.escape(sdir), path) + if m1: + # Check if the filename is in the ignore list. + m2 = re.search(r'(\s|^)%s(\s|$)' % re.escape(m1.group(1)), ignore_files) + if m2: + logging.info("Skipping path: %s", path) + return True + else: + logging.info("No match for: %s", m1.group(1)) + else: + logging.info("No match for: %s", path) + return False + + +def ReadSourceDocumentation(source_dir, suffix_list, ignore_files): + """Read the documentation embedded in comment blocks in the source code. + + It recursively descends the source directory looking for source files and + scans them looking for specially-formatted comment blocks. + + Args: + source_dir (str): the directory to scan. + suffix_list (list): extensions to check + ignore_files (list): a list of ignored paths under source_dir + """ + logging.info("Scanning source directory: %s", source_dir) + + # This array holds any subdirectories found. + subdirs = [] + + for ifile in sorted(os.listdir(source_dir)): + logging.debug("... : %s", ifile) + if ifile.startswith('.'): + continue + fname = os.path.join(source_dir, ifile) + if os.path.isdir(fname): + subdirs.append(fname) + elif fname in ignore_files: + logging.info(f"File {fname} matches ignored files") + else: + for suffix in suffix_list: + if ifile.endswith(suffix): + ScanSourceFile(fname, ignore_files) + break + + # Now recursively scan the subdirectories. + for sdir in subdirs: + if sdir in ignore_files: + logging.info(f"Directory {sdir} matches ignored files") + continue + ReadSourceDocumentation(sdir, suffix_list, ignore_files) + + +def ScanSourceFile(ifile, ignore_files): + """Scans one source file looking for specially-formatted comment blocks. + + Later MergeSourceDocumentation() is copying over the doc blobs that are not + suppressed/ignored. + + Args: + ifile (str): the file to scan. + """ + m = re.search(r'^.*[\/\\]([^\/\\]*)$', ifile) + if m: + basename = m.group(1) + else: + common.LogWarning(ifile, 1, "Can't find basename for this filename.") + basename = ifile + + # Check if the filename is in the list of files to ignore. + if ifile in ignore_files: + logging.info("Skipping source file: %s", ifile) + return + + logging.info("Scanning %s", ifile) + + with open(ifile, 'r', encoding='utf-8') as src: + input_lines = src.readlines() + + for c in ScanSourceContent(input_lines, ifile): + ParseCommentBlock(c[0], c[1], ifile) + + logging.info("Scanning %s done", ifile) + + +def ScanSourceContent(input_lines, ifile=''): + """Scans the source code lines for specially-formatted comment blocks. + + Updates global state in SourceSymbolDocs, SymbolSourceLocation, + Since, StabilityLevel, Deprecated, SymbolAnnotations. + + Might read from global state in DeclarationTypes + + Args: + input_lines (list): list of source code lines + ifile (str): file name of the source file (for reporting) + + Returns: + list: tuples with comment block and its starting line + """ + comments = [] + in_comment_block = False + line_number = 0 + comment = [] + starting_line = 0 + for line in input_lines: + line_number += 1 + + if not in_comment_block: + # Look for the start of a comment block. + if re.search(r'^\s*/\*.*\*/', line): + # one-line comment - not gtkdoc + pass + elif re.search(r'^\s*/\*\*\s', line): + logging.info("Found comment block start") + + in_comment_block = True + comment = [] + starting_line = line_number + 1 + else: + # Look for end of comment + if re.search(r'^\s*\*+/', line): + comments.append((comment, starting_line)) + in_comment_block = False + continue + + # Get rid of ' * ' at start of every line in the comment block. + line = re.sub(r'^\s*\*\s?', '', line) + # But make sure we don't get rid of the newline at the end. + if not line.endswith('\n'): + line += "\n" + + logging.info("scanning :%s", line.strip()) + comment.append(line) + + return comments + + +def SegmentCommentBlock(lines, line_number=0, ifile=''): + """Cut a single comment block into segments. + + Args: + lines (list): the comment block + line_number (int): the first line of the block (for reporting) + ifile (str): file name of the source file (for reporting) + + Returns: + (str, dict): symbol name and dict of comment segments + """ + symbol = None + in_part = '' + segments = {'body': ''} + params = OrderedDict() + param_name = None + param_indent = None + line_number -= 1 + for line in lines: + line_number += 1 + logging.info("scanning[%s] :%s", in_part, line.strip()) + + # If we haven't found the symbol name yet, look for it. + # We need to allow for the following cases: + # function: + # Class::signal: + # Class:property: + # Class|action: + # Signal and property names can contain dashes, action names + # can contain period. + # In all cases, there might be annotations in parentheses + # following the symbol name. + if not symbol: + m1 = re.search(r'^\s*((SECTION|PROGRAM):\s*\S+)', line) + m2 = re.search(r'^\s*([\w:.|-]*\w)\s*:?\s*(\(.+?\)\s*)*$', line) + if m1: + symbol = m1.group(1) + logging.info("docs found in source for : '%s'", symbol) + elif m2: + symbol = m2.group(1) + logging.info("docs found in source for : '%s'", symbol) + if m2.group(2): + annotation = m2.group(2).strip() + if annotation != '': + SymbolAnnotations[symbol] = annotation + logging.info("remaining text for %s: '%s'", symbol, annotation) + + continue + + if in_part == "body": + # Get rid of 'Description:' + line = re.sub(r'^\s*Description:', '', line) + + m1 = re.search(r'^\s*(returns|return\s+value):', line, flags=re.I) + m2 = re.search(r'^\s*since:', line, flags=re.I) + m3 = re.search(r'^\s*deprecated:', line, flags=re.I) + m4 = re.search(r'^\s*stability:', line, flags=re.I) + + if m1: + if in_part != '': + in_part = "return" + segments[in_part] = line[m1.end():] + continue + if m2: + if in_part != "param": + in_part = "since" + segments[in_part] = line[m2.end():] + continue + elif m3: + if in_part != "param": + in_part = "deprecated" + segments[in_part] = line[m3.end():] + continue + elif m4: + in_part = "stability" + segments[in_part] = line[m4.end():] + continue + + if in_part in ["body", "return", "since", "stability", "deprecated"]: + segments[in_part] += line + continue + + # We must be in the parameters. Check for the empty line below them. + if re.search(r'^\s*$', line): + # TODO: only switch if next line starts without indent? + in_part = "body" + continue + + # Look for a parameter name. + m = re.search(r'^\s*@(.+?)\s*:\s*', line) + if m: + param_name = m.group(1) + param_desc = line[m.end():] + param_indent = None + + # Allow varargs variations + if re.search(r'^\.\.\.$', param_name): + param_name = "..." + + logging.info("Found param for symbol %s : '%s'= '%s'", symbol, param_name, line) + params[param_name] = param_desc + in_part = "param" + continue + elif in_part == '': + logging.info("continuation for %s annotation '%s'", symbol, line) + annotation = re.sub(r'^\s+|\s+$', '', line) + if symbol in SymbolAnnotations: + SymbolAnnotations[symbol] += annotation + else: + SymbolAnnotations[symbol] = annotation + continue + + # We must be in the middle of a parameter description, so add it on + # to the last element in @params. + if not param_name: + common.LogWarning(ifile, line_number, + "Parsing comment block file : parameter expected, but got '%s'" % line) + else: + if not param_indent: + # determine indentation of first continuation line + spc = len(line) - len(line.lstrip(' ')) + if spc > 0: + param_indent = spc + logging.debug("Found param-indentation of %d", param_indent) + if param_indent: + # cut common indentation (after double checking that it is all spaces) + if line[:param_indent].strip() == '': + line = line[param_indent:] + else: + logging.warning("Not cutting param-indentation for %s: '%s'", + param_name, line[:param_indent]) + + params[param_name] += line + + return (symbol, segments, params) + + +def ParseCommentBlockSegments(symbol, segments, params, line_number=0, ifile=''): + """Parse the comemnts block segments. + + Args: + symbol (str): the symbol name + segments(dict): the comment block segments (except params) + parans (dict): the comment block params + line_number (int): the first line of the block (for reporting) + ifile (str): file name of the source file (for reporting) + + """ + # Add the return value description to the end of the params. + if "return" in segments: + # TODO(ensonic): check for duplicated Return docs + # common.LogWarning(file, line_number, "Multiple Returns for %s." % symbol) + params['Returns'] = segments["return"] + + # Convert special characters + segments["body"] = ConvertXMLChars(symbol, segments["body"]) + for (param_name, param_desc) in params.items(): + params[param_name] = ConvertXMLChars(symbol, param_desc) + + # Handle Section docs + m = re.search(r'SECTION:\s*(.*)', symbol) + m2 = re.search(r'PROGRAM:\s*(.*)', symbol) + if m: + real_symbol = m.group(1) + + logging.info("SECTION DOCS found in source for : '%s'", real_symbol) + for param_name, param_desc in params.items(): + logging.info(" '" + param_name + "'") + param_name = param_name.lower() + if param_name in ['image', 'include', 'section_id', 'see_also', 'short_description', 'stability', 'title']: + key = real_symbol + ':' + param_name + SourceSymbolDocs[key] = param_desc + SymbolSourceLocation[key] = (ifile, line_number) + + key = real_symbol + ":long_description" + if key not in KnownSymbols or KnownSymbols[key] != 1: + common.LogWarning( + ifile, line_number, "Section %s is not defined in the %s-sections.txt file." % (real_symbol, MODULE)) + SourceSymbolDocs[key] = segments["body"] + SymbolSourceLocation[key] = (ifile, line_number) + elif m2: + real_symbol = m2.group(1) + section_id = None + + logging.info("PROGRAM DOCS found in source for '%s'", real_symbol) + for param_name, param_desc in params.items(): + logging.info("PROGRAM key %s: '%s'", real_symbol, param_name) + param_name = param_name.lower() + if param_name in ['returns', 'section_id', 'see_also', 'short_description', 'synopsis']: + key = real_symbol + ':' + param_name + logging.info("PROGRAM value %s: '%s'", real_symbol, param_desc.rstrip()) + SourceSymbolDocs[key] = param_desc.rstrip() + SymbolSourceLocation[key] = (ifile, line_number) + elif re.search(r'^(-.*)', param_name): + logging.info("PROGRAM opts: '%s': '%s'", param_name, param_desc) + key = real_symbol + ":options" + opts = [] + opts_str = SourceSymbolDocs.get(key) + if opts_str: + opts = opts_str.split('\t') + opts.append(param_name) + opts.append(param_desc) + + logging.info("Setting options for symbol: %s: '%s'", real_symbol, '\t'.join(opts)) + SourceSymbolDocs[key] = '\t'.join(opts) + + key = real_symbol + ":long_description" + SourceSymbolDocs[key] = segments["body"] + SymbolSourceLocation[key] = (ifile, line_number) + + # TODO(ensonic): we need to track these somehow and output the files + # later, see comment in Run() + section_id = SourceSymbolDocs.get(real_symbol + ":section_id") + if section_id and section_id.strip() != '': + # Remove trailing blanks and use as is + section_id = section_id.rstrip() + else: + section_id = common.CreateValidSGMLID('%s-%s' % (MODULE, real_symbol)) + OutputProgramDBFile(real_symbol, section_id) + + else: + logging.info("SYMBOL DOCS found in source for : '%s'", symbol) + SourceSymbolDocs[symbol] = segments["body"] + SourceSymbolParams[symbol] = params + SymbolSourceLocation[symbol] = (ifile, line_number) + + if "since" in segments: + arr = segments["since"].splitlines() + desc = arr[0].strip() + extra_lines = arr[1:] + logging.info("Since(%s) : [%s]", symbol, desc) + Since[symbol] = ConvertXMLChars(symbol, desc) + if len(extra_lines) > 1: + common.LogWarning(ifile, line_number, "multi-line since docs found") + + if "stability" in segments: + desc = ParseStabilityLevel( + segments["stability"], ifile, line_number, "Stability level for %s" % symbol) + StabilityLevel[symbol] = ConvertXMLChars(symbol, desc) + + if "deprecated" in segments: + if symbol not in Deprecated: + # don't warn for signals and properties + # if ($symbol !~ m/::?(.*)/) + if symbol in DeclarationTypes: + common.LogWarning(ifile, line_number, + "%s is deprecated in the inline comments, but no deprecation guards were found around the declaration. (See the --deprecated-guards option for gtkdoc-scan.)" % symbol) + + Deprecated[symbol] = ConvertXMLChars(symbol, segments["deprecated"]) + + +def ParseCommentBlock(lines, line_number=0, ifile=''): + """Parse a single comment block. + + Args: + lines (list): the comment block + line_number (int): the first line of the block (for reporting) + ifile (str): file name of the source file (for reporting) + """ + (symbol, segments, params) = SegmentCommentBlock(lines, line_number, ifile) + if not symbol: + # maybe its not even meant to be a gtk-doc comment? + common.LogWarning(ifile, line_number, "Symbol name not found at the start of the comment block.") + return + + ParseCommentBlockSegments(symbol, segments, params, line_number, ifile) + + +def OutputMissingDocumentation(): + """Outputs report of documentation coverage to a file. + + Returns: + bool: True if the report was updated + """ + old_undocumented_file = os.path.join(ROOT_DIR, MODULE + "-undocumented.txt") + new_undocumented_file = os.path.join(ROOT_DIR, MODULE + "-undocumented.new") + + n_documented = 0 + n_incomplete = 0 + total = 0 + symbol = None + percent = None + buffer = '' + buffer_deprecated = '' + buffer_descriptions = '' + + UNDOCUMENTED = open(new_undocumented_file, 'w', encoding='utf-8') + + for symbol in sorted(AllSymbols.keys()): + # FIXME: should we print common.LogWarnings for undocumented stuff? + m = re.search( + r':(title|long_description|short_description|see_also|stability|include|section_id|image)', symbol) + m2 = re.search(r':(long_description|short_description)', symbol) + if not m: + total += 1 + if symbol in AllDocumentedSymbols: + n_documented += 1 + if symbol in AllIncompleteSymbols: + n_incomplete += 1 + buffer += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n" + + elif symbol in Deprecated: + if symbol in AllIncompleteSymbols: + n_incomplete += 1 + buffer_deprecated += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n" + else: + buffer_deprecated += symbol + "\n" + + else: + if symbol in AllIncompleteSymbols: + n_incomplete += 1 + buffer += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n" + else: + buffer += symbol + "\n" + + elif m2: + total += 1 + if (symbol in SymbolDocs and len(SymbolDocs[symbol]) > 0)\ + or (symbol in AllDocumentedSymbols and AllDocumentedSymbols[symbol] > 0): + n_documented += 1 + else: + buffer_descriptions += symbol + "\n" + + if total == 0: + percent = 100 + else: + percent = (n_documented / total) * 100.0 + + UNDOCUMENTED.write("%.0f%% symbol docs coverage.\n" % percent) + UNDOCUMENTED.write("%s symbols documented.\n" % n_documented) + UNDOCUMENTED.write("%s symbols incomplete.\n" % n_incomplete) + UNDOCUMENTED.write("%d not documented.\n" % (total - n_documented)) + + if buffer_deprecated != '': + buffer += "\n" + buffer_deprecated + + if buffer_descriptions != '': + buffer += "\n" + buffer_descriptions + + if buffer != '': + UNDOCUMENTED.write("\n\n" + buffer) + + UNDOCUMENTED.close() + + return common.UpdateFileIfChanged(old_undocumented_file, new_undocumented_file, 0) + + +def OutputUndeclaredSymbols(): + """Reports undeclared symbols. + + Outputs symbols that are listed in the section file, but have no declaration + in the sources. + + Returns: + bool: True if the report was updated + """ + old_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.txt") + new_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.new") + + with open(new_undeclared_file, 'w', encoding='utf-8') as out: + if UndeclaredSymbols: + out.write("\n".join(sorted(UndeclaredSymbols.keys()))) + out.write("\n") + print("See %s-undeclared.txt for the list of undeclared symbols." % MODULE) + + return common.UpdateFileIfChanged(old_undeclared_file, new_undeclared_file, 0) + + +def OutputUnusedSymbols(): + """Reports unused documentation. + + Outputs symbols that are documented in comments, but not declared in the + sources. + + Returns: + bool: True if the report was updated + """ + num_unused = 0 + old_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.txt") + new_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.new") + + with open(new_unused_file, 'w', encoding='utf-8') as out: + + for symbol in sorted(Declarations.keys()): + if symbol not in DeclarationOutput: + out.write("%s\n" % symbol) + num_unused += 1 + + for symbol in sorted(AllUnusedSymbols.keys()): + out.write(symbol + "(" + AllUnusedSymbols[symbol] + ")\n") + num_unused += 1 + + if num_unused != 0: + common.LogWarning( + old_unused_file, 1, "%d unused declarations. They should be added to %s-sections.txt in the appropriate place." % (num_unused, MODULE)) + + return common.UpdateFileIfChanged(old_unused_file, new_unused_file, 0) + + +def OutputAllSymbols(): + """Outputs list of all symbols to a file.""" + new_symbols_file = os.path.join(ROOT_DIR, MODULE + "-symbols.txt") + with open(new_symbols_file, 'w', encoding='utf-8') as out: + for symbol in sorted(AllSymbols.keys()): + out.write(symbol + "\n") + + +def OutputSymbolsWithoutSince(): + """Outputs list of all symbols without a since tag to a file.""" + new_nosince_file = os.path.join(ROOT_DIR, MODULE + "-nosince.txt") + with open(new_nosince_file, 'w', encoding='utf-8') as out: + for symbol in sorted(SourceSymbolDocs.keys()): + if symbol in Since: + out.write(symbol + "\n") + + +def CheckParamsDocumented(symbol, params): + stype = DeclarationTypes.get(symbol) + + item = "Parameter" + if stype: + if stype == 'STRUCT': + item = "Field" + elif stype == 'ENUM': + item = "Value" + elif stype == 'UNION': + item = "Field" + else: + stype = "SIGNAL" + logging.info("Check param docs for %s, params: %s entries, type=%s", symbol, len(params), stype) + + if len(params) > 0: + logging.info("params: %s", str(params)) + for (param_name, param_desc) in params.items(): + # Output a warning if the parameter is empty and remember for stats. + if param_name != "void" and not re.search(r'\S', param_desc): + if symbol in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] += ", " + param_name + else: + AllIncompleteSymbols[symbol] = param_name + + common.LogWarning(*GetSymbolSourceLocation(symbol), + "%s description for %s::%s is missing in source code comment block." % (item, symbol, param_name)) + + elif len(params) == 0: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(*GetSymbolSourceLocation(symbol), + "%s descriptions for %s are missing in source code comment block." % (item, symbol)) + + +def MergeSourceDocumentation(): + """Merges documentation read from a source file. + + Parameter descriptions override any in the template files. + Function descriptions are placed before any description from + the template files. + """ + + # add what's found in the source + symbols = set(SourceSymbolDocs.keys()) + + # and add known symbols from -sections.txt + for symbol in KnownSymbols.keys(): + if KnownSymbols[symbol] == 1: + symbols.add(symbol) + + logging.info("num source entries: %d", len(symbols)) + + for symbol in symbols: + AllSymbols[symbol] = 1 + + if symbol in SourceSymbolDocs: + logging.info("merging [%s] from source", symbol) + + # remove leading and training whitespaces + src_docs = SourceSymbolDocs[symbol].strip() + if src_docs != '': + AllDocumentedSymbols[symbol] = 1 + + SymbolDocs[symbol] = src_docs + + # merge parameters + if symbol in SourceSymbolParams: + param_docs = SourceSymbolParams[symbol] + SymbolParams[symbol] = param_docs + # if this symbol is documented, check if docs are complete + # remove all xml-tags and whitespaces + check_docs = re.sub(r'\s', '', re.sub(r'<.*?>', '', src_docs)) + if check_docs != '' and param_docs: + CheckParamsDocumented(symbol, param_docs) + else: + logging.info("[%s] undocumented", symbol) + + logging.info("num doc entries: %d / %d", len(SymbolDocs), len(SourceSymbolDocs)) + + +def IsEmptyDoc(doc): + """Check if a doc-string is empty. + + It is also regarded as empty if it only consist of whitespace or e.g. FIXME. + + Args: + doc (str): the doc-string + + Returns: + bool: True if empty + """ + if re.search(r'^\s*$', doc): + return True + if re.search(r'^\s*\s*(FIXME)?\s*<\/para>\s*$', doc): + return True + return False + + +def ConvertMarkDown(symbol, text): + md_to_db.Init() + return md_to_db.MarkDownParse(text, symbol) + + +def ReadDeclarationsFile(ifile, override): + """Reads in a file containing the function/macro/enum etc. declarations. + + Note that in some cases there are several declarations with + the same name, e.g. for conditional macros. In this case we + set a flag in the DeclarationConditional hash so the + declaration is not shown in the docs. + + If a macro and a function have the same name, e.g. for + g_object_ref, the function declaration takes precedence. + + Some opaque structs are just declared with 'typedef struct + _name name;' in which case the declaration may be empty. + The structure may have been found later in the header, so + that overrides the empty declaration. + + Args: + file (str): the declarations file to read + override (bool): if declarations in this file should override + any current declaration. + """ + if override == 0: + Declarations.clear() + DeclarationTypes.clear() + DeclarationConditional.clear() + DeclarationOutput.clear() + + INPUT = open(ifile, 'r', encoding='utf-8') + declaration_type = '' + declaration_name = None + declaration = None + is_deprecated = 0 + line_number = 0 + for line in INPUT: + line_number += 1 + # logging.debug("%s:%d: %s", ifile, line_number, line) + if not declaration_type: + m1 = re.search(r'^<([^>]+)>', line) + if m1: + declaration_type = m1.group(1) + declaration_name = '' + logging.info("Found declaration: %s", declaration_type) + declaration = '' + else: + m2 = re.search(r'^(.*)', line) + m3 = re.search(r'^', line) + m4 = re.search(r'^' % declaration_type, line) + if m2: + declaration_name = m2.group(1) + elif m3: + is_deprecated = True + elif m4: + logging.info("Found end of declaration: %s, %s", declaration_type, declaration_name) + # Check that the declaration has a name + if declaration_name == '': + common.LogWarning(ifile, line_number, declaration_type + " has no name.\n") + + # If the declaration is an empty typedef struct _XXX XXX + # set the flag to indicate the struct has a typedef. + if (declaration_type == 'STRUCT' or declaration_type == 'UNION') \ + and re.search(r'^\s*$', declaration): + logging.info("Struct has typedef: %s", declaration_name) + StructHasTypedef[declaration_name] = 1 + + # Check if the symbol is already defined. + if declaration_name in Declarations and override == 0: + # Function declarations take precedence. + if DeclarationTypes[declaration_name] == 'FUNCTION': + # Ignore it. + pass + elif declaration_type == 'FUNCTION': + if is_deprecated: + Deprecated[declaration_name] = '' + + Declarations[declaration_name] = declaration + DeclarationTypes[declaration_name] = declaration_type + elif DeclarationTypes[declaration_name] == declaration_type: + # If the existing declaration is empty, or is just a + # forward declaration of a struct, override it. + if declaration_type == 'STRUCT' or declaration_type == 'UNION': + if re.search(r'^\s*((struct|union)\s+\w+\s*;)?\s*$', Declarations[declaration_name]): + if is_deprecated: + Deprecated[declaration_name] = '' + Declarations[declaration_name] = declaration + elif re.search(r'^\s*((struct|union)\s+\w+\s*;)?\s*$', declaration): + # Ignore an empty or forward declaration. + pass + else: + common.LogWarning( + ifile, line_number, "Structure %s has multiple definitions." % declaration_name) + + else: + # set flag in %DeclarationConditional hash for + # multiply defined macros/typedefs. + DeclarationConditional[declaration_name] = 1 + + else: + common.LogWarning(ifile, line_number, declaration_name + " has multiple definitions.") + + else: + if is_deprecated: + Deprecated[declaration_name] = '' + + Declarations[declaration_name] = declaration + DeclarationTypes[declaration_name] = declaration_type + logging.debug("added declaration: %s, %s, [%s]", declaration_type, declaration_name, declaration) + + declaration_type = '' + is_deprecated = False + else: + declaration += line + INPUT.close() + + +def ReadSignalsFile(ifile): + """Reads information about object signals. + + It creates the arrays @SignalNames and @SignalPrototypes containing details + about the signals. The first line of the SignalPrototype is the return type + of the signal handler. The remaining lines are the parameters passed to it. + The last parameter, "gpointer user_data" is always the same so is not included. + + Args: + ifile (str): the file containing the signal handler prototype information. + """ + in_signal = 0 + signal_object = None + signal_name = None + signal_returns = None + signal_flags = None + signal_prototype = None + + # Reset the signal info. + SignalObjects[:] = [] + SignalNames[:] = [] + SignalReturns[:] = [] + SignalFlags[:] = [] + SignalPrototypes[:] = [] + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile, 'r', encoding='utf-8') + line_number = 0 + for line in INPUT: + line_number += 1 + if not in_signal: + if re.search(r'^', line): + in_signal = 1 + signal_object = '' + signal_name = '' + signal_returns = '' + signal_prototype = '' + + else: + m = re.search(r'^(.*)<\/NAME>', line) + m2 = re.search(r'^(.*)<\/RETURNS>', line) + m3 = re.search(r'^(.*)<\/FLAGS>', line) + if m: + signal_name = m.group(1) + m1_2 = re.search(r'^(.*)::(.*)$', signal_name) + if m1_2: + signal_object = m1_2.group(1) + signal_name = m1_2.group(2).replace('_', '-') + logging.info("Found signal: %s", signal_name) + else: + common.LogWarning(ifile, line_number, "Invalid signal name: %s." % signal_name) + + elif m2: + signal_returns = m2.group(1) + elif m3: + signal_flags = m3.group(1) + elif re.search(r'^', line): + logging.info("Found end of signal: %s::%s\nReturns: %s\n%s", + signal_object, signal_name, signal_returns, signal_prototype) + SignalObjects.append(signal_object) + SignalNames.append(signal_name) + SignalReturns.append(signal_returns) + SignalFlags.append(signal_flags) + SignalPrototypes.append(signal_prototype) + in_signal = False + else: + signal_prototype += line + INPUT.close() + + +def ReadObjectHierarchy(ifile): + """Reads the $MODULE-hierarchy file. + + This contains all the GObject subclasses described in this module (and their + ancestors). + It places them in the Objects array, and places their level + in the object hierarchy in the ObjectLevels array, at the + same index. GObject, the root object, has a level of 1. + + Args: + ifile (str): the input filename. + """ + + if not os.path.isfile(ifile): + logging.debug('no %s file found', ifile) + return + + Objects[:] = [] + ObjectLevels[:] = [] + + INPUT = open(ifile, 'r', encoding='utf-8') + + # Only emit objects if they are supposed to be documented, or if + # they have documented children. To implement this, we maintain a + # stack of pending objects which will be emitted if a documented + # child turns up. + pending_objects = [] + pending_levels = [] + root = None + tree = [] + for line in INPUT: + m1 = re.search(r'\S+', line) + if not m1: + continue + + gobject = m1.group(0) + level = len(line[:m1.start()]) // 2 + 1 + + if level == 1: + root = gobject + + while pending_levels and pending_levels[-1] >= level: + pending_objects.pop() + pending_levels.pop() + + pending_objects.append(gobject) + pending_levels.append(level) + + if gobject in KnownSymbols: + while len(pending_levels) > 0: + gobject = pending_objects.pop(0) + level = pending_levels.pop(0) + xref = MakeXRef(gobject) + + tree.append(' ' * (level * 4) + xref) + Objects.append(gobject) + ObjectLevels.append(level) + ObjectRoots[gobject] = root + # else + # common.LogWarning(ifile, line_number, "unknown type %s" % object) + # + + INPUT.close() + logging.debug('got %d entries for hierarchy', len(tree)) + return tree + + +def ReadInterfaces(ifile): + """Reads the $MODULE.interfaces file. + + Args: + ifile (str): the input filename. + """ + + Interfaces.clear() + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile, 'r', encoding='utf-8') + + for line in INPUT: + line = line.strip() + ifaces = line.split() + gobject = ifaces.pop(0) + if gobject in KnownSymbols and KnownSymbols[gobject] == 1: + knownIfaces = [] + + # filter out private interfaces, but leave foreign interfaces + for iface in ifaces: + if iface not in KnownSymbols or KnownSymbols[iface] == 1: + knownIfaces.append(iface) + + Interfaces[gobject] = ' '.join(knownIfaces) + logging.info("Interfaces for %s: %s", gobject, Interfaces[gobject]) + else: + logging.info("skipping interfaces for unknown symbol: %s", gobject) + + INPUT.close() + + +def ReadPrerequisites(ifile): + """This reads in the $MODULE.prerequisites file. + + Args: + ifile (str): the input filename. + """ + Prerequisites.clear() + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile, 'r', encoding='utf-8') + + for line in INPUT: + line = line.strip() + prereqs = line.split() + iface = prereqs.pop(0) + if iface in KnownSymbols and KnownSymbols[iface] == 1: + knownPrereqs = [] + + # filter out private prerequisites, but leave foreign prerequisites + for prereq in prereqs: + if prereq not in KnownSymbols or KnownSymbols[prereq] == 1: + knownPrereqs.append(prereq) + + Prerequisites[iface] = ' '.join(knownPrereqs) + + INPUT.close() + + +def ReadArgsFile(ifile): + """Reads information about object properties + + It creates the arrays ArgObjects, ArgNames, ArgTypes, ArgFlags, ArgNicks and + ArgBlurbs containing info on the args. + + Args: + ifile (str): the input filename. + """ + in_arg = False + arg_object = None + arg_name = None + arg_type = None + arg_flags = None + arg_nick = None + arg_blurb = None + arg_default = None + arg_range = None + + # Reset the args info. + ArgObjects[:] = [] + ArgNames[:] = [] + ArgTypes[:] = [] + ArgFlags[:] = [] + ArgNicks[:] = [] + ArgBlurbs[:] = [] + ArgDefaults[:] = [] + ArgRanges[:] = [] + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile, 'r', encoding='utf-8') + line_number = 0 + for line in INPUT: + line_number += 1 + if not in_arg: + if line.startswith(''): + in_arg = True + arg_object = '' + arg_name = '' + arg_type = '' + arg_flags = '' + arg_nick = '' + arg_blurb = '' + arg_default = '' + arg_range = '' + + else: + m1 = re.search(r'^(.*)', line) + m2 = re.search(r'^(.*)', line) + m3 = re.search(r'^(.*)', line) + m4 = re.search(r'^(.*)', line) + m5 = re.search(r'^(.*)', line) + m6 = re.search(r'^(.*)', line) + m7 = re.search(r'^(.*)', line) + if m1: + arg_name = m1.group(1) + m1_1 = re.search(r'^(.*)::(.*)$', arg_name) + if m1_1: + arg_object = m1_1.group(1) + arg_name = m1_1.group(2).replace('_', '-') + logging.info("Found arg: %s", arg_name) + else: + common.LogWarning(ifile, line_number, "Invalid argument name: " + arg_name) + + elif m2: + arg_type = m2.group(1) + elif m3: + arg_range = m3.group(1) + elif m4: + arg_flags = m4.group(1) + elif m5: + arg_nick = m5.group(1) + elif m6: + arg_blurb = m6.group(1) + if arg_blurb == "(null)": + arg_blurb = '' + common.LogWarning( + ifile, line_number, "Property %s:%s has no documentation." % (arg_object, arg_name)) + + elif m7: + arg_default = m7.group(1) + elif re.search(r'^', line): + logging.info("Found end of arg: %s::%s\n%s : %s", arg_object, arg_name, arg_type, arg_flags) + ArgObjects.append(arg_object) + ArgNames.append(arg_name) + ArgTypes.append(arg_type) + ArgRanges.append(arg_range) + ArgFlags.append(arg_flags) + ArgNicks.append(arg_nick) + ArgBlurbs.append(arg_blurb) + ArgDefaults.append(arg_default) + in_arg = False + + INPUT.close() + +def ReadActionsFile(ifile): + """Reads information about object actions + + It creates the arrays ActionObjects, ActionNames, ActionParams + and ActionProperties containing info on the actions. + + Args: + ifile (str): the input filename. + """ + in_action = False + action_object = None + action_name = None + action_param = None + action_prop = None + + # Reset the args info. + ActionObjects[:] = [] + ActionNames[:] = [] + ActionParams[:] = [] + ActionProperties[:] = [] + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile, 'r', encoding='utf-8') + line_number = 0 + for line in INPUT: + line_number += 1 + if not in_action: + if line.startswith(''): + in_action = True + action_object = '' + action_name = '' + action_param = '' + action_prop = '' + + else: + m1 = re.search(r'^(.*)', line) + m2 = re.search(r'^(.*)', line) + m3 = re.search(r'^(.*)', line) + if m1: + action_name = m1.group(1) + m1_1 = re.search(r'^(.*):::(.*)$', action_name) + if m1_1: + action_object = m1_1.group(1) + action_name = m1_1.group(2).replace('_', '-') + logging.info("Found action: %s", action_name) + else: + common.LogWarning(ifile, line_number, "Invalid action name: " + action_name) + + elif m2: + action_param = m2.group(1) + elif m3: + action_prop = m3.group(1) + elif re.search(r'^', line): + logging.info("Found end of action: %s::%s", action_object, action_name) + ActionObjects.append(action_object) + ActionNames.append(action_name) + ActionParams.append(action_param) + ActionProperties.append(action_prop) + in_action = False + + INPUT.close() + + +def AddTreeLineArt(tree): + """Generate a line art tree. + + Add unicode lineart to a pre-indented string array and returns + it as as multiline string. + + Args: + tree (list): of indented strings. + + Returns: + str: multiline string with tree line art + """ + # iterate bottom up over the tree + for i in range(len(tree) - 1, -1, -1): + # count leading spaces + m = re.search(r'^([^ 4: + if tree[i][indent - 4] == " ": + tree[i] = tree[i][:indent - 4] + "--- " + tree[i][indent:] + else: + tree[i] = tree[i][:indent - 4] + "+-- " + tree[i][indent:] + + # go lines up while space and insert | + j = i - 1 + while j >= 0 and tree[j][indent - 4] == ' ': + tree[j] = tree[j][:indent - 4] + '|' + tree[j][indent - 3:] + j -= 1 + + res = "\n".join(tree) + # unicode chars for: ╰── + res = re.sub(r'---', '╰──', res) + # unicde chars for: ├── + res = re.sub(r'\+--', '├──', res) + # unicode char for: │ + res = re.sub(r'\|', '│', res) + + return res + + +def CheckIsObject(name): + """Check if symbols is an object. + + It uses the global Objects array. Note that the Objects array only contains + classes in the current module and their ancestors - not all GObject classes. + + Args: + name (str): the object name to check. + + Returns: + bool: True if the given name is a GObject or a subclass. + """ + root = ObjectRoots.get(name) + # Let GBoxed pass as an object here to get -struct appended to the id + # and prevent conflicts with sections. + return root and root != 'GEnum' and root != 'GFlags' + + +def GetSymbolParams(symbol): + """Get the symbol params and check that they are not empty. + + If no parameters are filled in, we don't generate the description table, + for backwards compatibility. + + Args: + symbol: the symbol to check the parameters for + + Returns: + dict: The parameters + bool: True if empty + """ + params = SymbolParams.get(symbol, {}) + # TODO: strip at parsing stage? + found = next((True for p in params.values() if p.strip() != ''), False) + return (params, found) + + +def GetSymbolSourceLocation(symbol): + """Get the filename and line where the symbol docs where taken from.""" + return SymbolSourceLocation.get(symbol, ('', 0)) diff --git a/gtk-doc-for-gtk4/gtkdoc/mkhtml.py b/gtk-doc-for-gtk4/gtkdoc/mkhtml.py new file mode 100644 index 0000000000..52df3f4eb8 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/mkhtml.py @@ -0,0 +1,90 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Owen Taylor +# 2001-2005 Damon Chaplin +# 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import logging +import os +import sys +import subprocess +import shutil +from glob import glob + +from . import config + + +def run_xsltproc(options, args): + command = [config.xsltproc] + # we could do "$path_option $PWD " to avoid needing rewriting entities that + # are copied from the header into docs under xml + if os.environ.get("GTKDOC_PROFILE", '') == '': + if len(options.path): + command += ['--path', ':'.join(options.path)] + logging.info('running "%s"', ' '.join(command + args)) + return subprocess.call(command + args) + else: + command += ['--profile'] + if len(options.path): + command += ['--path', ':'.join(options.path)] + logging.info('running "%s"', ' '.join(command + args)) + return subprocess.call(command + args, stderr=open('profile.txt', 'w')) + + +def run(options): + logging.info('options: %s', str(options.__dict__)) + + module = options.args[0] + document = options.args[1] + if options.verbose: + quiet = '0' + else: + quiet = '1' + remaining_args = options.args[2:] + + (gtkdocdir, styledir) = config.get_dirs(options.uninstalled) + + res = run_xsltproc(options, [ + '--nonet', + '--xinclude', + '--stringparam', + 'gtkdoc.bookname', + module, + '--stringparam', + 'gtkdoc.version', + config.version, + '--stringparam', + 'chunk.quietly', + quiet, + '--stringparam', + 'chunker.output.quiet', + quiet] + remaining_args + [gtkdocdir + '/gtk-doc.xsl', document]) + + # profiling + if os.environ.get("GTKDOC_PROFILE", '') != '': + subprocess.check_call('cat profile.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o profile.png', shell=True) + + # copy navigation images and stylesheets to html directory ... + for f in glob(styledir + '/*.png') + glob(styledir + '/*.css'): + shutil.copy(f, '.') + + with open('../html.stamp', 'w') as h: + h.write('timestamp') + return res diff --git a/gtk-doc-for-gtk4/gtkdoc/mkhtml2.py b/gtk-doc-for-gtk4/gtkdoc/mkhtml2.py new file mode 100644 index 0000000000..2eb5c73c40 --- /dev/null +++ b/gtk-doc-for-gtk4/gtkdoc/mkhtml2.py @@ -0,0 +1,1871 @@ +#!/usr/bin/env python3 +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2018 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +"""Generate html from docbook + +The tool loads the main xml document (-docs.xml) and chunks it +like the xsl-stylesheets would do. For that it resolves all the xml-includes. +Each chunk is converted to html using python functions. + +In contrast to our previous approach of running gtkdoc-mkhtml + gtkdoc-fixxref, +this tools will replace both without relying on external tools such as xsltproc +and source-highlight. + +Please note, that we're not aiming for complete docbook-xml support. All tags +used in the generated xml are of course handled. More tags used in handwritten +xml can be easily supported, but for some combinations of tags we prefer +simplicity. + +TODO: +- tag converters: + - 'section'/'simplesect' - the first we convert as a chunk, the nested ones we + need to convert as 'sect{2,3,4,...}, we can track depth in 'ctx' + - inside 'footnote' one can have many tags, we only handle 'para'/'simpara' + - inside 'glossentry' we're only handling 'glossterm' and 'glossdef' + - convert_{figure,table} need counters. +- check each docbook tag if it can contain #PCDATA, if not don't check for + xml.text/xml.tail and add a comment (# no PCDATA allowed here) +- find a better way to print context for warnings + - we use 'xml.sourceline', but this all does not help a lot due to xi:include +- consolidate title handling: + - always use the titles-dict + - convert_title(): uses titles.get(tid)['title'] + - convert_xref(): uses titles[tid]['tag'], ['title'] and ['xml'] + - create_devhelp2_refsect2_keyword(): uses titles[tid]['title'] + - there only store what we have (xml, tag, ...) + - when chunking generate 'id's and add entries to titles-dict + - add accessors for title and raw_title that lazily get them + - see if any of the other ~10 places that call convert_title() could use this + cache +- performance + - consider some perf-warnings flag + - see 'No "id" attribute on' + - xinclude processing in libxml2 is slow + - if we disable it, we get '{http://www.w3.org/2003/XInclude}include' tags + and we could try handling them ourself, in some cases those are subtrees + that we extract for chunking anyway + +DIFFERENCES: +- titles + - we add the chunk label to the title in toc, on the page and in nav tooltips + - docbook xsl only sometimes adds the label to the titles and when it does it + adds name chunk type too (e.g. 'Part I.' instead of 'I.') +- navigation + - we always add an up-link except on the first page +- footer + - we're nov omitting the footer +- tocs + - we always add "Table of Contents' before a toc + - docbook does that for some pages, it is configurable + +OPTIONAL: +- minify html: https://pypi.python.org/pypi/htmlmin/ + +Requirements: +sudo pip3 install anytree lxml pygments + +Example invocation: +cd tests/bugs/docs/ +mkdir -p db2html +cd dbhtml +../../../../gtkdoc-mkhtml2 tester ../tester-docs.xml +cd .. +xdg-open db2html/index.html +meld html db2html + +Benchmarking: +cd tests/bugs/docs/; +rm html-build.stamp; time make html-build.stamp +""" + +import logging +import os +import shutil +import sys + +from anytree import Node, PreOrderIter +from copy import deepcopy +from glob import glob +from lxml import etree +from timeit import default_timer as timer + +from . import config, highlight, fixxref + + +class ChunkParams(object): + def __init__(self, prefix, parent=None, min_idx=0): + self.prefix = prefix + self.parent = parent + self.min_idx = min_idx + self.idx = 1 + + +DONT_CHUNK = float('inf') +# docbook-xsl defines the chunk tags here. +# http://www.sagehill.net/docbookxsl/Chunking.html#GeneratedFilenames +# https://github.com/oreillymedia/HTMLBook/blob/master/htmlbook-xsl/chunk.xsl#L33 +# If not defined, we can just create an example without an 'id' attr and see +# docbook xsl does. +# +# For toc levels see http://www.sagehill.net/docbookxsl/TOCcontrol.html +# TODO: this list has also a flag that controls whether we add the +# 'Table of Contents' heading in convert_chunk_with_toc() +CHUNK_PARAMS = { + 'appendix': ChunkParams('app', 'book'), + 'book': ChunkParams('bk'), + 'chapter': ChunkParams('ch', 'book'), + 'glossary': ChunkParams('go', 'book'), + 'index': ChunkParams('ix', 'book'), + 'part': ChunkParams('pt', 'book'), + 'preface': ChunkParams('pr', 'book'), + 'refentry': ChunkParams('re', 'book'), + 'reference': ChunkParams('rn', 'book'), + 'sect1': ChunkParams('s', 'chapter', 1), + 'section': ChunkParams('s', 'chapter', 1), + 'sect2': ChunkParams('s', 'sect1', DONT_CHUNK), + 'sect3': ChunkParams('s', 'sect2', DONT_CHUNK), + 'sect4': ChunkParams('s', 'sect3', DONT_CHUNK), + 'sect5': ChunkParams('s', 'sect4', DONT_CHUNK), +} +# TAGS we don't support: +# 'article', 'bibliography', 'colophon', 'set', 'setindex' + +TITLE_XPATHS = { + '_': (etree.XPath('./title'), None), + 'book': (etree.XPath('./bookinfo/title'), None), + 'refentry': ( + etree.XPath('./refmeta/refentrytitle'), + etree.XPath('./refnamediv/refpurpose') + ), +} + +ID_XPATH = etree.XPath('//*[@id]') + +GLOSSENTRY_XPATH = etree.XPath('//glossentry') +glossary = {} + +footnote_idx = 1 + +# nested dict with subkeys: +# title: textual title +# tag: chunk tag +# xml: title xml node +titles = {} + +# files to copy +assets = set() + + +def encode_entities(text): + return text.replace('&', '&').replace('<', '<').replace('>', '>') + + +def raw_text(xml): + return etree.tostring(xml, method="text", encoding=str).strip() + + +def gen_chunk_name(node, chunk_params): + """Generate a chunk file name + + This is either based on the id or on the position in the doc. In the latter + case it uses a prefix from CHUNK_PARAMS and a sequence number for each chunk + type. + """ + idval = node.attrib.get('id') + if idval is not None: + return idval + + name = ('%s%02d' % (chunk_params.prefix, chunk_params.idx)) + chunk_params.idx += 1 + + # handle parents to make names of nested tags like in docbook + # - we only need to prepend the parent if there are > 1 of them in the + # xml. None, the parents we have are not sufficient, e.g. 'index' can + # be in 'book' or 'part' or ... Maybe we can track the chunk_parents + # when we chunk explicitly and on each level maintain the 'idx' + # while chunk_params.parent: + # parent = chunk_params.parent + # if parent not in CHUNK_PARAMS: + # break; + # chunk_params = CHUNK_PARAMS[parent] + # name = ('%s%02d' % (chunk_params.prefix, chunk_params.idx)) + name + + logging.info('Gen chunk name: "%s"', name) + return name + + +def get_chunk_titles(module, node, tree_node): + tag = node.tag + (title, subtitle) = TITLE_XPATHS.get(tag, TITLE_XPATHS['_']) + + ctx = { + 'module': module, + 'files': [], + 'node': tree_node, + } + result = { + 'title': None, + 'title_tag': None, + 'subtitle': None, + 'subtitle_tag': None + } + res = title(node) + if res: + # handle chunk label for tocs + label = node.attrib.get('label') + if label: + label += '. ' + else: + label = '' + + xml = res[0] + # TODO: consider to eval 'title'/'raw_title' lazily + result['title'] = label + ''.join(convert_title(ctx, xml)) + result['raw_title'] = encode_entities(raw_text(xml)) + if xml.tag != 'title': + result['title_tag'] = xml.tag + else: + result['title_tag'] = tag + + if subtitle: + res = subtitle(node) + if res: + xml = res[0] + result['subtitle'] = ''.join(convert_title(ctx, xml)) + result['subtitle_tag'] = xml.tag + return result + + +def chunk(xml_node, module, depth=0, idx=0, parent=None): + """Chunk the tree. + + The first time, we're called with parent=None and in that case we return + the new_node as the root of the tree. For each tree-node we generate a + filename and process the children. + """ + tag = xml_node.tag + chunk_params = CHUNK_PARAMS.get(tag) + if chunk_params: + title_args = get_chunk_titles(module, xml_node, parent) + chunk_name = gen_chunk_name(xml_node, chunk_params) + + # check idx to handle 'sect1'/'section' special casing and title-only + # segments + if idx >= chunk_params.min_idx: + logging.info('chunk tag: "%s"[%d]', tag, idx) + if parent: + # remove the xml-node from the parent + sub_tree = etree.ElementTree(deepcopy(xml_node)).getroot() + xml_node.getparent().remove(xml_node) + xml_node = sub_tree + + parent = Node(tag, parent=parent, xml=xml_node, depth=depth, + idx=idx, + filename=chunk_name + '.html', anchor=None, + **title_args) + else: + parent = Node(tag, parent=parent, xml=xml_node, depth=depth, + idx=idx, + filename=parent.filename, anchor='#' + chunk_name, + **title_args) + + depth += 1 + idx = 0 + for child in xml_node: + chunk(child, module, depth, idx, parent) + if child.tag in CHUNK_PARAMS: + idx += 1 + + return parent + + +def add_id_links_and_titles(files, links): + for node in files: + chunk_name = node.filename[:-5] + chunk_base = node.filename + '#' + for elem in ID_XPATH(node.xml): + attr = elem.attrib['id'] + if attr == chunk_name: + links[attr] = node.filename + else: + links[attr] = chunk_base + attr + + title = TITLE_XPATHS.get(elem.tag, TITLE_XPATHS['_'])[0] + res = title(elem) + if res: + xml = res[0] + # TODO: consider to eval 'title' lazily + titles[attr] = { + 'title': encode_entities(raw_text(xml)), + 'xml': xml, + 'tag': elem.tag, + } + + +def build_glossary(files): + for node in files: + if node.xml.tag != 'glossary': + continue + for term in GLOSSENTRY_XPATH(node.xml): + # TODO: there can be all kind of things in a glossary. This only supports + # what we commonly use, glossterm is mandatory + key_node = term.find('glossterm') + val_node = term.find('glossdef') + if key_node is not None and val_node is not None: + glossary[raw_text(key_node)] = raw_text(val_node) + else: + debug = [] + if key_node is None: + debug.append('missing key') + if val_node is None: + debug.append('missing val') + logging.warning('Broken glossentry "%s": %s', + term.attrib['id'], ','.join(debug)) + + +# conversion helpers + + +def convert_inner(ctx, xml, result): + for child in xml: + result.extend(convert_tags.get(child.tag, convert__unknown)(ctx, child)) + + +def convert_ignore(ctx, xml): + result = [] + convert_inner(ctx, xml, result) + return result + + +def convert_skip(ctx, xml): + return [] + + +def append_idref(attrib, result): + idval = attrib.get('id') + if idval is not None: + result.append('' % idval) + + +def append_text(ctx, text, result): + if text and ('no-strip' in ctx or text.strip()): + result.append(encode_entities(text)) + + +missing_tags = {} + + +def convert__unknown(ctx, xml): + # don't recurse on subchunks + if xml.tag in CHUNK_PARAMS: + return [] + if isinstance(xml, etree._Comment): + return ['\n'] + else: + # warn only once + if xml.tag not in missing_tags: + logging.warning('Add tag converter for "%s"', xml.tag) + missing_tags[xml.tag] = True + result = ['\n'] + convert_inner(ctx, xml, result) + result.append('\n') + return result + + +def convert_mediaobject_children(ctx, xml, result): + # look for textobject/phrase + alt_text = '' + textobject = xml.find('textobject') + if textobject is not None: + phrase = textobject.findtext('phrase') + if phrase: + alt_text = ' alt="%s"' % phrase + + # look for imageobject/imagedata + imageobject = xml.find('imageobject') + if imageobject is not None: + imagedata = imageobject.find('imagedata') + if imagedata is not None: + # TODO(ensonic): warn on missing fileref attr? + fileref = imagedata.attrib.get('fileref', '') + if fileref: + assets.add(fileref) + result.append('' % (fileref, alt_text)) + + +def convert_sect(ctx, xml, h_tag, inner_func=convert_inner): + result = ['
\n' % xml.tag] + title_tag = xml.find('title') + if title_tag is not None: + append_idref(xml.attrib, result) + result.append('<%s>%s' % ( + h_tag, ''.join(convert_title(ctx, title_tag)), h_tag)) + append_text(ctx, xml.text, result) + inner_func(ctx, xml, result) + result.append('
') + append_text(ctx, xml.tail, result) + return result + + +def xml_get_title(ctx, xml): + title_tag = xml.find('title') + if title_tag is not None: + return ''.join(convert_title(ctx, title_tag)) + else: + logging.warning('%s: Expected title tag under "%s %s"', xml.sourceline, xml.tag, str(xml.attrib)) + return '' + + +# docbook tags + + +def convert_abstract(ctx, xml): + result = ["""
+

Abstract

"""] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('
') + append_text(ctx, xml.tail, result) + return result + + +def convert_acronym(ctx, xml): + key = xml.text + title = glossary.get(key, '') + # TODO: print a sensible warning if missing + result = ['%s' % (title, key)] + if xml.tail: + result.append(xml.tail) + return result + + +def convert_anchor(ctx, xml): + return ['' % xml.attrib['id']] + + +def convert_bookinfo(ctx, xml): + result = ['
'] + convert_inner(ctx, xml, result) + result.append("""
+
""") + if xml.tail: + result.append(xml.tail) + return result + + +def convert_blockquote(ctx, xml): + result = ['
\n
'] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('
\n
') + append_text(ctx, xml.tail, result) + return result + + +def convert_code(ctx, xml): + result = ['' % xml.tag] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_colspec(ctx, xml): + result = ['\n') + # is in tgroup and there can be no 'text' + return result + + +def convert_command(ctx, xml): + result = [''] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_corpauthor(ctx, xml): + result = ['

\n'] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('

\n') + append_text(ctx, xml.tail, result) + return result + + +def convert_div(ctx, xml): + result = ['
\n' % xml.tag] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('
') + append_text(ctx, xml.tail, result) + return result + + +def convert_emphasis(ctx, xml): + role = xml.attrib.get('role') + if role is not None: + result = ['' % role] + end = '' + else: + result = [''] + end = '' + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append(end) + append_text(ctx, xml.tail, result) + return result + + +def convert_em(ctx, xml): + result = ['' % xml.tag] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_em_code(ctx, xml): + result = ['' % xml.tag] + append_idref(xml.attrib, result) + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_entry(ctx, xml): + entry_type = ctx['table.entry'] + result = ['<' + entry_type] + role = xml.attrib.get('role') + if role is not None: + result.append(' class="%s"' % role) + morerows = xml.attrib.get('morerows') + if morerows is not None: + result.append(' rowspan="%s"' % (1 + int(morerows))) + result.append('>') + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_figure(ctx, xml): + result = ['
\n'] + append_idref(xml.attrib, result) + title_tag = xml.find('title') + if title_tag is not None: + # TODO(ensonic): Add a 'Figure X. ' prefix, needs a figure counter + result.append('

%s

' % ''.join(convert_title(ctx, title_tag))) + result.append('
') + # TODO(ensonic): title can become alt on inner 'graphic' element + convert_inner(ctx, xml, result) + result.append('

') + append_text(ctx, xml.tail, result) + return result + + +def convert_footnote(ctx, xml): + footnotes = ctx.get('footnotes', []) + # footnotes idx is not per page, but per doc + global footnote_idx + idx = footnote_idx + footnote_idx += 1 + + # need a pair of ids for each footnote (docbook generates different ids) + this_id = 'footnote-%d' % idx + that_id = 'ftn.' + this_id + + inner = ['
' % that_id] + inner.append('

[%d] ' % ( + this_id, idx)) + # TODO(ensonic): this can contain all kind of tags, if we convert them we'll + # get double nested paras :/. + # convert_inner(ctx, xml, inner) + para = xml.find('para') + if para is None: + para = xml.find('simpara') + if para is not None: + inner.append(para.text) + else: + logging.warning('%s: Unhandled footnote content: %s', xml.sourceline, raw_text(xml)) + inner.append('

') + footnotes.append(inner) + ctx['footnotes'] = footnotes + return ['[%s]' % ( + that_id, this_id, idx)] + + +def convert_formalpara(ctx, xml): + result = None + title_tag = xml.find('title') + result = ['

%s' % ''.join(convert_title(ctx, title_tag))] + para_tag = xml.find('para') + append_text(ctx, para_tag.text, result) + convert_inner(ctx, para_tag, result) + append_text(ctx, para_tag.tail, result) + result.append('

') + append_text(ctx, xml.tail, result) + return result + + +def convert_glossdef(ctx, xml): + result = ['
'] + convert_inner(ctx, xml, result) + result.append('
\n') + return result + + +def convert_glossdiv(ctx, xml): + title_tag = xml.find('title') + title = title_tag.text + xml.remove(title_tag) + result = [ + '

%s

' % (title, title) + ] + convert_inner(ctx, xml, result) + return result + + +def convert_glossentry(ctx, xml): + result = [] + convert_inner(ctx, xml, result) + return result + + +def convert_glossterm(ctx, xml): + glossid = '' + text = '' + anchor = xml.find('anchor') + if anchor is not None: + glossid = anchor.attrib.get('id', '') + text += anchor.tail or '' + text += xml.text or '' + if glossid == '': + glossid = 'glossterm-' + text + return [ + '
%s
' % ( + glossid, text) + ] + + +def convert_graphic(ctx, xml): + # TODO(ensonic): warn on missing fileref attr? + fileref = xml.attrib.get('fileref', '') + if fileref: + assets.add(fileref) + return ['
' % fileref] + + +def convert_indexdiv(ctx, xml): + title_tag = xml.find('title') + title = title_tag.text + xml.remove(title_tag) + result = [ + '

%s

' % (title, title) + ] + convert_inner(ctx, xml, result) + return result + + +def convert_informaltable(ctx, xml): + result = ['
\n') + convert_inner(ctx, xml, result) + result.append('
') + if xml.tail: + result.append(xml.tail) + return result + + +def convert_inlinegraphic(ctx, xml): + # TODO(ensonic): warn on missing fileref attr? + fileref = xml.attrib.get('fileref', '') + if fileref: + assets.add(fileref) + return ['' % fileref] + + +def convert_inlinemediaobject(ctx, xml): + result = [''] + # no PCDATA allowed here + convert_mediaobject_children(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_itemizedlist(ctx, xml): + result = ['
    '] + convert_inner(ctx, xml, result) + result.append('
') + if xml.tail: + result.append(xml.tail) + return result + + +def convert_link(ctx, xml): + linkend = xml.attrib['linkend'] + result = [] + if linkend: + link_text = [] + append_text(ctx, xml.text, link_text) + convert_inner(ctx, xml, link_text) + text = ''.join(link_text) + + (tid, href) = fixxref.GetXRef(linkend) + if href: + title_attr = '' + title = titles.get(tid) + if title: + title_attr = ' title="%s"' % title['title'] + + href = fixxref.MakeRelativeXRef(ctx['module'], href) + result = ['%s' % (href, title_attr, text)] + else: + # TODO: filename is for the output and xml.sourceline is on the masterdoc ... + fixxref.ReportBadXRef(ctx['node'].filename, 0, linkend, text) + result = [text] + else: + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + append_text(ctx, xml.tail, result) + return result + + +def convert_listitem(ctx, xml): + result = ['
  • '] + convert_inner(ctx, xml, result) + result.append('
    • ') + # no PCDATA allowed here, is in itemizedlist + return result + + +def convert_literallayout(ctx, xml): + result = ['


    \n'] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('

    ') + append_text(ctx, xml.tail, result) + return result + + +def convert_mediaobject(ctx, xml): + result = ['
    \n'] + # no PCDATA allowed here + convert_mediaobject_children(ctx, xml, result) + result.append('
    ') + append_text(ctx, xml.tail, result) + return result + + +def convert_orderedlist(ctx, xml): + result = ['
      '] + convert_inner(ctx, xml, result) + result.append('
    ') + append_text(ctx, xml.tail, result) + return result + + +def convert_para(ctx, xml): + result = [] + role = xml.attrib.get('role') + if role is not None: + result.append('

    ' % role) + else: + result.append('

    ') + append_idref(xml.attrib, result) + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('

    ') + append_text(ctx, xml.tail, result) + return result + + +def convert_para_like(ctx, xml): + result = [] + append_idref(xml.attrib, result) + result.append('

    ' % xml.tag) + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('

    ') + append_text(ctx, xml.tail, result) + return result + + +def convert_phrase(ctx, xml): + result = ['' % role) + else: + result.append('>') + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_primaryie(ctx, xml): + result = ['
    \n'] + convert_inner(ctx, xml, result) + result.append('\n
    \n
    \n') + return result + + +def convert_pre(ctx, xml): + # Since we're inside 
     don't skip newlines
+    ctx['no-strip'] = True
+    result = ['
    ' % xml.tag]
+    append_text(ctx, xml.text, result)
+    convert_inner(ctx, xml, result)
+    result.append('
    ')
+    del ctx['no-strip']
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_programlisting(ctx, xml):
+    result = []
+    if xml.attrib.get('role', '') == 'example':
+        if xml.text:
+            lang = xml.attrib.get('language', ctx['src-lang']).lower()
+            highlighted = highlight.highlight_code(xml.text, lang)
+            if highlighted:
+                # we do own line-numbering
+                line_count = highlighted.count('\n')
+                source_lines = '\n'.join([str(i) for i in range(1, line_count + 1)])
+                result.append("""
+  
+    
+      
+      
+    
+  
+
    %s
    %s
    
+""" % (source_lines, highlighted))
+            else:
+                logging.warn('No pygments lexer for language="%s"', lang)
+                result.append('
    ')
+                result.append(xml.text)
+                result.append('
    ')
+    else:
+        result.append('
    ')
+        append_text(ctx, xml.text, result)
+        convert_inner(ctx, xml, result)
+        result.append('
    ')
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_quote(ctx, xml):
+    result = ['"']
+    append_text(ctx, xml.text, result)
+    convert_inner(ctx, xml, result)
+    result.append('"')
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_refsect1(ctx, xml):
+    # Add a divider between two consequitive refsect2
+    def convert_inner(ctx, xml, result):
+        prev = None
+        for child in xml:
+            if child.tag == 'refsect2' and prev is not None and prev.tag == child.tag:
+                result.append('
    \n')
+            result.extend(convert_tags.get(child.tag, convert__unknown)(ctx, child))
+            prev = child
+    return convert_sect(ctx, xml, 'h2', convert_inner)
+
+
+def convert_refsect2(ctx, xml):
+    return convert_sect(ctx, xml, 'h3')
+
+
+def convert_refsect3(ctx, xml):
+    return convert_sect(ctx, xml, 'h4')
+
+
+def convert_row(ctx, xml):
+    result = ['\n']
+    convert_inner(ctx, xml, result)
+    result.append('\n')
+    return result
+
+
+def convert_sbr(ctx, xml):
+    return ['
    ']
+
+
+def convert_sect1_tag(ctx, xml):
+    return convert_sect(ctx, xml, 'h2')
+
+
+def convert_sect2(ctx, xml):
+    return convert_sect(ctx, xml, 'h3')
+
+
+def convert_sect3(ctx, xml):
+    return convert_sect(ctx, xml, 'h4')
+
+
+def convert_simpara(ctx, xml):
+    result = ['
    ']
+    append_text(ctx, xml.text, result)
+    convert_inner(ctx, xml, result)
+    result.append('
    ')
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_span(ctx, xml):
+    result = ['' % xml.tag]
+    append_text(ctx, xml.text, result)
+    convert_inner(ctx, xml, result)
+    result.append('')
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_table(ctx, xml):
+    result = ['
    ']
+    append_idref(xml.attrib, result)
+    title_tag = xml.find('title')
+    if title_tag is not None:
+        result.append('
    ')
+        # TODO(ensonic): Add a 'Table X. ' prefix, needs a table counter
+        result.extend(convert_title(ctx, title_tag))
+        result.append('
    ')
+    result.append('
    ')
+
+    convert_inner(ctx, xml, result)
+
+    result.append('
    ')
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_tag(ctx, xml):
+    classval = xml.attrib.get('class')
+    if classval is not None:
+        result = ['' % classval]
+    else:
+        result = ['']
+    append_text(ctx, xml.text, result)
+    result.append('')
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_tbody(ctx, xml):
+    result = ['']
+    ctx['table.entry'] = 'td'
+    convert_inner(ctx, xml, result)
+    result.append('')
+    # is in tgroup and there can be no 'text'
+    return result
+
+
+def convert_tgroup(ctx, xml):
+    # tgroup does not expand to anything, but the nested colspecs need to
+    # be put into a colgroup
+    cols = xml.findall('colspec')
+    result = []
+    if cols:
+        result.append('\n')
+        for col in cols:
+            result.extend(convert_colspec(ctx, col))
+            xml.remove(col)
+        result.append('\n')
+    convert_inner(ctx, xml, result)
+    # is in informaltable and there can be no 'text'
+    return result
+
+
+def convert_thead(ctx, xml):
+    result = ['']
+    ctx['table.entry'] = 'th'
+    convert_inner(ctx, xml, result)
+    result.append('')
+    # is in tgroup and there can be no 'text'
+    return result
+
+
+def convert_title(ctx, xml):
+    # This is always explicitly called from some context
+    result = []
+    append_text(ctx, xml.text, result)
+    convert_inner(ctx, xml, result)
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_ulink(ctx, xml):
+    if xml.text:
+        result = ['%s' % (xml.tag, xml.attrib['url'], xml.text)]
+    else:
+        url = xml.attrib['url']
+        result = ['%s' % (xml.tag, url, url)]
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_userinput(ctx, xml):
+    result = ['']
+    append_text(ctx, xml.text, result)
+    convert_inner(ctx, xml, result)
+    result.append('')
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+def convert_variablelist(ctx, xml):
+    result = ["""
    
++++
+"""]
+    convert_inner(ctx, xml, result)
+    result.append("""
+
    



    """)
+    return result
+
+
+def convert_varlistentry(ctx, xml):
+    result = ['']
+
+    result.append('
    ')
+    term = xml.find('term')
+    result.extend(convert_span(ctx, term))
+    result.append('
    ')
+
+    result.append('')
+    listitem = xml.find('listitem')
+    convert_inner(ctx, listitem, result)
+    result.append('')
+
+    result.append('')
+    return result
+
+
+def convert_xref(ctx, xml):
+    result = []
+    linkend = xml.attrib['linkend']
+    (tid, href) = fixxref.GetXRef(linkend)
+    try:
+        title = titles[tid]
+        # all sectN need to become 'section
+        tag = title['tag']
+        tag = {
+            'sect1': 'section',
+            'sect2': 'section',
+            'sect3': 'section',
+            'sect4': 'section',
+            'sect5': 'section',
+        }.get(tag, tag)
+        result = [
+            'the %s called “%s”' %
+            (href, title['title'], tag, ''.join(convert_title(ctx, title['xml'])))
+        ]
+    except KeyError:
+        logging.warning('invalid linkend "%s"', tid)
+
+    append_text(ctx, xml.tail, result)
+    return result
+
+
+# TODO(ensonic): turn into class with converters as functions and ctx as self
+convert_tags = {
+    'abstract': convert_abstract,
+    'acronym': convert_acronym,
+    'anchor': convert_anchor,
+    'application': convert_span,
+    'bookinfo': convert_bookinfo,
+    'blockquote': convert_blockquote,
+    'classname': convert_code,
+    'caption': convert_div,
+    'code': convert_code,
+    'colspec': convert_colspec,
+    'constant': convert_code,
+    'command': convert_command,
+    'corpauthor': convert_corpauthor,
+    'emphasis': convert_emphasis,
+    'entry': convert_entry,
+    'envar': convert_code,
+    'footnote': convert_footnote,
+    'figure': convert_figure,
+    'filename': convert_code,
+    'firstterm': convert_em,
+    'formalpara': convert_formalpara,
+    'function': convert_code,
+    'glossdef': convert_glossdef,
+    'glossdiv': convert_glossdiv,
+    'glossentry': convert_glossentry,
+    'glossterm': convert_glossterm,
+    'graphic': convert_graphic,
+    'indexdiv': convert_indexdiv,
+    'indexentry': convert_ignore,
+    'indexterm': convert_skip,
+    'informalexample': convert_div,
+    'informaltable': convert_informaltable,
+    'inlinegraphic': convert_inlinegraphic,
+    'inlinemediaobject': convert_inlinemediaobject,
+    'interfacename': convert_code,
+    'itemizedlist': convert_itemizedlist,
+    'legalnotice': convert_div,
+    'link': convert_link,
+    'listitem': convert_listitem,
+    'literal': convert_code,
+    'literallayout': convert_literallayout,
+    'mediaobject': convert_mediaobject,
+    'note': convert_div,
+    'option': convert_code,
+    'orderedlist': convert_orderedlist,
+    'para': convert_para,
+    'partintro': convert_div,
+    'parameter': convert_em_code,
+    'phrase': convert_phrase,
+    'primaryie': convert_primaryie,
+    'programlisting': convert_programlisting,
+    'quote': convert_quote,
+    'releaseinfo': convert_para_like,
+    'refsect1': convert_refsect1,
+    'refsect2': convert_refsect2,
+    'refsect3': convert_refsect3,
+    'replaceable': convert_em_code,
+    'returnvalue': convert_span,
+    'row': convert_row,
+    'sbr': convert_sbr,
+    'screen': convert_pre,
+    'section': convert_sect2,      # FIXME: need tracking of nesting
+    'sect1': convert_sect1_tag,
+    'sect2': convert_sect2,
+    'sect3': convert_sect3,
+    'simpara': convert_simpara,
+    'simplesect': convert_sect2,   # FIXME: need tracking of nesting
+    'structfield': convert_em_code,
+    'structname': convert_span,
+    'synopsis': convert_pre,
+    'symbol': convert_span,
+    'table': convert_table,
+    'tag': convert_tag,
+    'tbody': convert_tbody,
+    'term': convert_span,
+    'tgroup': convert_tgroup,
+    'thead': convert_thead,
+    'title': convert_skip,
+    'type': convert_span,
+    'ulink': convert_ulink,
+    'userinput': convert_userinput,
+    'varname': convert_code,
+    'variablelist': convert_variablelist,
+    'varlistentry': convert_varlistentry,
+    'warning': convert_div,
+    'xref': convert_xref,
+}
+
+# conversion helpers
+
+HTML_HEADER = """
+
+
+
+%s
+%s
+
+
+"""
+
+
+def generate_head_links(ctx):
+    n = ctx['nav_home']
+    result = [
+        '\n' % (n.filename, n.raw_title)
+    ]
+
+    n = ctx.get('nav_up')
+    if n is not None:
+        result.append('\n' % (n.filename, n.raw_title))
+
+    n = ctx.get('nav_prev')
+    if n is not None:
+        result.append('\n' % (n.filename, n.raw_title))
+
+    n = ctx.get('nav_next')
+    if n is not None:
+        result.append('\n' % (n.filename, n.raw_title))
+
+    return ''.join(result)
+
+
+def generate_nav_links(ctx):
+    n = ctx['nav_home']
+    result = [
+        'Home' % n.filename
+    ]
+
+    n = ctx.get('nav_up')
+    if n is not None:
+        result.append(
+            'Up' % n.filename)
+    else:
+        result.append('')
+
+    n = ctx.get('nav_prev')
+    if n is not None:
+        result.append(
+            'Prev' % n.filename)
+    else:
+        result.append('')
+
+    n = ctx.get('nav_next')
+    if n is not None:
+        result.append(
+            'Next' % n.filename)
+    else:
+        result.append('')
+
+    return ''.join(result)
+
+
+def generate_toc(ctx, node):
+    result = []
+    for c in node.children:
+        # TODO: urlencode the filename: urllib.parse.quote_plus()
+        link = c.filename
+        if c.anchor:
+            link += c.anchor
+        result.append('
    %s\n' % (
+            c.title_tag, link, c.title))
+        if c.subtitle:
+            result.append(' — %s' % (c.subtitle_tag, c.subtitle))
+        result.append('
    \n')
+        if c.children:
+            result.append('
    ')
+            result.extend(generate_toc(ctx, c))
+            result.append('
    ')
+    return result
+
+
+def generate_basic_nav(ctx):
+    return """
+  
+    
+    %s
+  
+
+    """ % generate_nav_links(ctx)
+
+
+def generate_alpha_nav(ctx, divs, prefix, span_id):
+    ix_nav = []
+    for s in divs:
+        title = xml_get_title(ctx, s)
+        ix_nav.append('%s' % (prefix, title, title))
+
+    return """
+  
+    
+    %s
+  
+
+    """ % (span_id, '\n|\n'.join(ix_nav), generate_nav_links(ctx))
+
+
+def generate_refentry_nav(ctx, refsect1s, result):
+    result.append("""
+  
+    
+    %s
+  
+
+""" % generate_nav_links(ctx))
+
+
+def generate_footer(ctx):
+    footnotes = ctx.get('footnotes')
+    if footnotes is None:
+        return []
+
+    result = ["""
    \n
+
    
+"""]
+    for f in footnotes:
+        result.extend(f)
+    result.append('
    \n')
+    return result
+
+
+def get_id_path(node):
+    """ Generate the 'id'.
+    We need to walk up the xml-tree and check the positions for each sibling.
+    When reaching the top of the tree we collect remaining index entries from
+    the chunked-tree.
+    """
+    ix = []
+    xml = node.xml
+    parent = xml.getparent()
+    while parent is not None:
+        children = parent.getchildren()
+        ix.insert(0, str(children.index(xml) + 1))
+        xml = parent
+        parent = xml.getparent()
+    while node is not None:
+        ix.insert(0, str(node.idx + 1))
+        node = node.parent
+
+    return ix
+
+
+def get_id(node):
+    xml = node.xml
+    node_id = xml.attrib.get('id', None)
+    if node_id:
+        return node_id
+
+    # TODO: this is moot if nothing links to it, we could also consider to omit
+    # the  tag.
+    logging.info('%d: No "id" attribute on "%s", generating one',
+                 xml.sourceline, xml.tag)
+    ix = get_id_path(node)
+    # logging.warning('%s: id indexes: %s', node.filename, str(ix))
+    return 'id-' + '.'.join(ix)
+
+
+def convert_chunk_with_toc(ctx, div_class, title_tag):
+    node = ctx['node']
+    result = [
+        HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
+        generate_basic_nav(ctx),
+        '
    ' % div_class,
+    ]
+    if node.title:
+        result.append("""
+
    
+<%s class="title">%s
+
    """ % (
+            title_tag, get_id(node), node.title, title_tag))
+
+    toc = generate_toc(ctx, node)
+    if toc:
+        # TODO: not all docbook page types use this extra heading
+        result.append("""
    Table of Contents
    
+    
    
+      
    
+    """)
+        result.extend(toc)
+        result.append("""
    
+    
    
+    """)
+    convert_inner(ctx, node.xml, result)
+    result.extend(generate_footer(ctx))
+    result.append("""
    
+
+""")
+    return result
+
+
+# docbook chunks
+
+
+def convert_book(ctx):
+    node = ctx['node']
+    result = [
+        HTML_HEADER % (node.title, generate_head_links(ctx)),
+        """
+    
+
+
    
+""" % node.title
+    ]
+    bookinfo = node.xml.findall('bookinfo')[0]
+    result.extend(convert_bookinfo(ctx, bookinfo))
+    result.append("""
    
+  
    
+""")
+    result.extend(generate_toc(ctx, node.root))
+    result.append("""
    
+
    
+""")
+    result.extend(generate_footer(ctx))
+    result.append("""
    
+
+""")
+    return result
+
+
+def convert_chapter(ctx):
+    return convert_chunk_with_toc(ctx, 'chapter', 'h2')
+
+
+def convert_glossary(ctx):
+    node = ctx['node']
+    glossdivs = node.xml.findall('glossdiv')
+
+    result = [
+        HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
+        generate_alpha_nav(ctx, glossdivs, 'gls', 'glossary'),
+        """
    
+
    
+%s
+
    """ % (node.depth, get_id(node), node.title, node.depth)
+    ]
+    for i in glossdivs:
+        result.extend(convert_glossdiv(ctx, i))
+    result.extend(generate_footer(ctx))
+    result.append("""
    
+
+""")
+    return result
+
+
+def convert_index(ctx):
+    node = ctx['node']
+    # Get all indexdivs under indexdiv
+    indexdivs = []
+    indexdiv = node.xml.find('indexdiv')
+    if indexdiv is not None:
+        indexdivs = indexdiv.findall('indexdiv')
+
+    result = [
+        HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
+        generate_alpha_nav(ctx, indexdivs, 'idx', 'index'),
+        """
    
+
    
+%s
+
    """ % (node.depth, get_id(node), node.title, node.depth)
+    ]
+    for i in indexdivs:
+        result.extend(convert_indexdiv(ctx, i))
+    result.extend(generate_footer(ctx))
+    result.append("""
    
+
+""")
+    return result
+
+
+def convert_part(ctx):
+    return convert_chunk_with_toc(ctx, 'part', 'h1')
+
+
+def convert_preface(ctx):
+    node = ctx['node']
+    result = [
+        HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
+        generate_basic_nav(ctx),
+        '
    '
+    ]
+    if node.title:
+        result.append("""
+
    
+
    %s
    
+
    """ % (get_id(node), node.title))
+    convert_inner(ctx, node.xml, result)
+    result.extend(generate_footer(ctx))
+    result.append("""
    
+
+""")
+    return result
+
+
+def convert_reference(ctx):
+    return convert_chunk_with_toc(ctx, 'reference', 'h1')
+
+
+def convert_refentry(ctx):
+    node = ctx['node']
+    node_id = get_id(node)
+    refsect1s = node.xml.findall('refsect1')
+
+    gallery = ''
+    refmeta = node.xml.find('refmeta')
+    if refmeta is not None:
+        refmiscinfo = refmeta.find('refmiscinfo')
+        if refmiscinfo is not None:
+            inlinegraphic = refmiscinfo.find('inlinegraphic')
+            if inlinegraphic is not None:
+                gallery = ''.join(convert_inlinegraphic(ctx, inlinegraphic))
+
+    result = [
+        HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx))
+    ]
+    generate_refentry_nav(ctx, refsect1s, result)
+    result.append("""
+
    
+
+
    
+  
+    
+    
+  
    
+      
    %s
    
+      
    %s — %s
    
+        		%s
    
+
    
+""" % (node_id, node_id, node.title, node.title, node.subtitle, gallery))
+
+    for s in refsect1s:
+        result.extend(convert_refsect1(ctx, s))
+    result.extend(generate_footer(ctx))
+    result.append("""
    
+
+""")
+    return result
+
+
+def convert_section(ctx):
+    return convert_chunk_with_toc(ctx, 'section', 'h2')
+
+
+def convert_sect1(ctx):
+    return convert_chunk_with_toc(ctx, 'sect1', 'h2')
+
+
+# TODO(ensonic): turn into class with converters as functions and ctx as self
+convert_chunks = {
+    'book': convert_book,
+    'chapter': convert_chapter,
+    'glossary': convert_glossary,
+    'index': convert_index,
+    'part': convert_part,
+    'preface': convert_preface,
+    'reference': convert_reference,
+    'refentry': convert_refentry,
+    'section': convert_section,
+    'sect1': convert_sect1,
+}
+
+
+def generate_nav_nodes(files, node):
+    nav = {
+        'nav_home': node.root,
+    }
+    # nav params: up, prev, next
+    if node.parent:
+        nav['nav_up'] = node.parent
+    ix = files.index(node)
+    if ix > 0:
+        nav['nav_prev'] = files[ix - 1]
+    if ix < len(files) - 1:
+        nav['nav_next'] = files[ix + 1]
+    return nav
+
+
+def convert_content(module, files, node, src_lang):
+    converter = convert_chunks.get(node.name)
+    if converter is None:
+        logging.warning('Add chunk converter for "%s"', node.name)
+        return []
+
+    ctx = {
+        'module': module,
+        'files': files,
+        'node': node,
+        'src-lang': src_lang,
+    }
+    ctx.update(generate_nav_nodes(files, node))
+    return converter(ctx)
+
+
+def convert(out_dir, module, files, node, src_lang):
+    """Convert the docbook chunks to a html file.
+
+    Args:
+      out_dir: already created output dir
+      files: list of nodes in the tree in pre-order
+      node: current tree node
+    """
+
+    logging.info('Writing: %s', node.filename)
+    with open(os.path.join(out_dir, node.filename), 'wt',
+              newline='\n', encoding='utf-8') as html:
+        for line in convert_content(module, files, node, src_lang):
+            html.write(line)
+
+
+def create_devhelp2_toc(node):
+    result = []
+    for c in node.children:
+        if c.children:
+            result.append('\n' % (c.raw_title, c.filename))
+            result.extend(create_devhelp2_toc(c))
+            result.append('\n')
+        else:
+            result.append('\n' % (c.raw_title, c.filename))
+    return result
+
+
+def create_devhelp2_condition_attribs(node):
+    condition = node.attrib.get('condition')
+    if condition is not None:
+        # condition -> since, deprecated, ... (separated with '|')
+        cond = condition.replace('"', '"').split('|')
+        keywords = []
+        for c in cond:
+            if ':' in c:
+                keywords.append('{}="{}"'.format(*c.split(':', 1)))
+            else:
+                # deprecated can have no description
+                keywords.append('{}="{}"'.format(c, ''))
+        return ' ' + ' '.join(keywords)
+    else:
+        return ''
+
+
+def create_devhelp2_refsect2_keyword(node, base_link):
+    node_id = node.attrib['id']
+    return'    \n' % (
+        node.attrib['role'], titles[node_id]['title'], base_link + node_id,
+        create_devhelp2_condition_attribs(node))
+
+
+def create_devhelp2_refsect3_keyword(node, base_link, title, name):
+    return'    \n' % (
+        node.attrib['role'], title, base_link + name,
+        create_devhelp2_condition_attribs(node))
+
+
+def create_devhelp2_content(module, xml, files):
+    title = ''
+    online_attr = ''
+    bookinfo_nodes = xml.xpath('/book/bookinfo')
+    if len(bookinfo_nodes):
+        bookinfo = bookinfo_nodes[0]
+        title = bookinfo.xpath('./title/text()')[0]
+        online_url = bookinfo.xpath('./releaseinfo/ulink[@role="online-location"]/@url')
+        if len(online_url):
+            online_attr = ' online="' + online_url[0] + '"'
+        # TODO: support author too (see devhelp2.xsl), it is hardly used though
+        # locate *.devhelp2 | xargs grep -Hn --color ' author="[^"]'
+    # TODO: fixxref uses '--src-lang' to set the language, we have this in options too
+    result = [
+        """
+
+  
+""" % (title, module, online_attr)
+    ]
+    # toc
+    result.extend(create_devhelp2_toc(files[0].root))
+    result.append("""  
+  
+""")
+    # keywords from all refsect2 and refsect3
+    refsect2 = etree.XPath('//refsect2[@role]')
+    refsect3_enum = etree.XPath('refsect3[@role="enum_members"]/informaltable/tgroup/tbody/row[@role="constant"]')
+    refsect3_enum_details = etree.XPath('entry[@role="enum_member_name"]/para')
+    refsect3_struct = etree.XPath('refsect3[@role="struct_members"]/informaltable/tgroup/tbody/row[@role="member"]')
+    refsect3_struct_details = etree.XPath('entry[@role="struct_member_name"]/para/structfield')
+    for node in files:
+        base_link = node.filename + '#'
+        refsect2_nodes = refsect2(node.xml)
+        for refsect2_node in refsect2_nodes:
+            result.append(create_devhelp2_refsect2_keyword(refsect2_node, base_link))
+            refsect3_nodes = refsect3_enum(refsect2_node)
+            for refsect3_node in refsect3_nodes:
+                details_node = refsect3_enum_details(refsect3_node)[0]
+                name = details_node.attrib['id']
+                result.append(create_devhelp2_refsect3_keyword(refsect3_node, base_link, details_node.text, name))
+            refsect3_nodes = refsect3_struct(refsect2_node)
+            for refsect3_node in refsect3_nodes:
+                details_node = refsect3_struct_details(refsect3_node)[0]
+                name = details_node.attrib['id']
+                result.append(create_devhelp2_refsect3_keyword(refsect3_node, base_link, name, name))
+
+    result.append("""  
+
+""")
+    return result
+
+
+def create_devhelp2(out_dir, module, xml, files):
+    with open(os.path.join(out_dir, module + '.devhelp2'), 'wt',
+              newline='\n', encoding='utf-8') as idx:
+        for line in create_devhelp2_content(module, xml, files):
+            idx.write(line)
+
+
+class FakeDTDResolver(etree.Resolver):
+    """Don't load the docbookx.dtd since we disable the validation anyway.
+
+    libxsml2 does not cache DTDs. If we produce a docbook file with 100 chunks
+    loading such a doc with xincluding will load and parse the docbook DTD 100
+    times. This cases tons of memory allocations and is slow.
+    """
+
+    def resolve(self, url, id, context):
+        if not url.endswith('.dtd'):
+            return None
+        # http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
+        return self.resolve_string('', context)
+
+
+def main(module, index_file, out_dir, uninstalled, src_lang, paths):
+
+    # == Loading phase ==
+    # the next 3 steps could be done in parallel
+
+    # 1) load the docuemnt
+    _t = timer()
+    parser = etree.XMLParser(dtd_validation=False, collect_ids=False)
+    parser.resolvers.add(FakeDTDResolver())
+    tree = etree.parse(index_file, parser)
+    logging.warning("1a: %7.3lf: load doc", timer() - _t)
+    _t = timer()
+    tree.xinclude()
+    logging.warning("1b: %7.3lf: xinclude doc", timer() - _t)
+
+    # 2) copy datafiles
+    _t = timer()
+    # TODO: handle additional images
+    (gtkdocdir, styledir) = config.get_dirs(uninstalled)
+    # copy navigation images and stylesheets to html directory ...
+    css_file = os.path.join(styledir, 'style.css')
+    for f in glob(os.path.join(styledir, '*.png')) + [css_file]:
+        shutil.copy(f, out_dir)
+    highlight.append_style_defs(os.path.join(out_dir, 'style.css'))
+    logging.warning("2: %7.3lf: copy datafiles", timer() - _t)
+
+    # 3) load xref targets
+    _t = timer()
+    # TODO: migrate options from fixxref
+    # TODO: ideally explicitly specify the files we need, this will save us the
+    # globbing and we'll load less files.
+    fixxref.LoadIndicies(out_dir, '/usr/share/gtk-doc/html', [])
+    logging.warning("3: %7.3lf: load xrefs", timer() - _t)
+
+    # == Processing phase ==
+
+    # 4) recursively walk the tree and chunk it into a python tree so that we
+    #    can generate navigation and link tags.
+    _t = timer()
+    files = chunk(tree.getroot(), module)
+    files = [f for f in PreOrderIter(files) if f.anchor is None]
+    logging.warning("4: %7.3lf: chunk doc", timer() - _t)
+
+    # 5) extract tables:
+    _t = timer()
+    # TODO: can be done in parallel
+    # - find all 'id' attribs and add them to the link map
+    # - .. get their titles and store them into the titles map
+    add_id_links_and_titles(files, fixxref.Links)
+    # - build glossary dict
+    build_glossary(files)
+    logging.warning("5: %7.3lf: extract tables", timer() - _t)
+
+    # == Output phase ==
+    # the next two step could be done in parllel
+
+    # 6) create a xxx.devhelp2 file
+    _t = timer()
+    create_devhelp2(out_dir, module, tree.getroot(), files)
+    logging.warning("6: %7.3lf: create devhelp2", timer() - _t)
+
+    # 7) iterate the tree and output files
+    _t = timer()
+    # TODO: can be done in parallel, figure out why this is not faster
+    # from multiprocessing.pool import Pool
+    # with Pool(4) as p:
+    #     p.apply_async(convert, args=(out_dir, module, files))
+    # from multiprocessing.pool import ThreadPool
+    # with ThreadPool(4) as p:
+    #     p.apply_async(convert, args=(out_dir, module, files))
+    for node in files:
+        convert(out_dir, module, files, node, src_lang)
+    logging.warning("7: %7.3lf: create html", timer() - _t)
+
+    # 8) copy assets over
+    _t = timer()
+    paths = set(paths + [os.getcwd()])
+    for a in assets:
+        logging.info('trying %s in %s', a, str(paths))
+        copied = False
+        for p in paths:
+            try:
+                shutil.copy(os.path.join(p, a), out_dir)
+                copied = True
+            except FileNotFoundError:
+                pass
+        if not copied:
+            logging.warning('file %s not found in path (did you add --path?)', a)
+    logging.warning("8: %7.3lf: copy assets", timer() - _t)
+
+
+def run(options):
+    logging.info('options: %s', str(options.__dict__))
+    module = options.args[0]
+    document = options.args[1]
+
+    output_dir = options.output_dir or os.getcmd()
+    if options.output_dir and not os.path.isdir(output_dir):
+        os.mkdir(output_dir)
+
+    # TODO: pass options.extra_dir
+    sys.exit(main(module, document, output_dir, options.uninstalled, options.src_lang,
+                  options.path))
diff --git a/gtk-doc-for-gtk4/gtkdoc/mkman.py b/gtk-doc-for-gtk4/gtkdoc/mkman.py
new file mode 100644
index 0000000000..f1725f5328
--- /dev/null
+++ b/gtk-doc-for-gtk4/gtkdoc/mkman.py
@@ -0,0 +1,65 @@
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Owen Taylor
+#               2001-2005 Damon Chaplin
+#               2009-2017  Stefan Sauer
+#               2017  Jussi Pakkanen
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+import logging
+import subprocess
+
+from . import config
+
+
+def run(options):
+    logging.info('options: %s', str(options.__dict__))
+
+    module = options.args[0]
+    document = options.args[1]
+    if options.verbose:
+        quiet = '0'
+    else:
+        quiet = '1'
+
+    # we could do "--path $PWD " to avoid needing rewriting entities that
+    # are copied from the header into docs under xml
+    path_arg = []
+    for path in options.path:
+        path_arg += ['--path', path]
+
+    # would it make sense to create man pages only for certain refentries
+    # e.g. for tools
+    # see http://bugzilla.gnome.org/show_bug.cgi?id=467488
+    return subprocess.call([config.xsltproc] + path_arg + [
+        '--nonet',
+        '--xinclude',
+        '--stringparam',
+        'gtkdoc.bookname',
+        module,
+        '--stringparam',
+        'gtkdoc.version',
+        config.version,
+        '--stringparam',
+        'chunk.quietly ',
+        quiet,
+        '--stringparam',
+        'chunker.output.quiet',
+        quiet,
+        'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
+        document])
diff --git a/gtk-doc-for-gtk4/gtkdoc/mkpdf.py b/gtk-doc-for-gtk4/gtkdoc/mkpdf.py
new file mode 100755
index 0000000000..c7c75bfb48
--- /dev/null
+++ b/gtk-doc-for-gtk4/gtkdoc/mkpdf.py
@@ -0,0 +1,122 @@
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2009-2017  Stefan Sauer
+#               2017  Jussi Pakkanen
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+import logging
+import os
+import sys
+import subprocess
+
+from . import config
+
+
+def run_xsltproc(options, args):
+    command = [config.xsltproc]
+    # we could do "--path $PWD " to avoid needing rewriting entities that are
+    # copied from the header into docs under xml
+    if len(options.path):
+        command += ['--path', ':'.join(options.path)]
+    logging.info('running "%s"', ' '.join(command + args))
+    pc = subprocess.Popen(command + args, stderr=subprocess.PIPE)
+    (o, stde) = pc.communicate()
+    with open('profile.txt', 'wb') as h:
+        h.write(stde)
+    return pc.returncode
+
+
+def run(options):
+    logging.info('options: %s', str(options.__dict__))
+
+    module = options.args[0]
+    document = options.args[1]
+
+    gtkdocdir, _ = config.get_dirs(options.uninstalled)
+
+    if config.dblatex != '':
+        # extra options to consider
+        # -I FIG_PATH
+        # -V is useful for debugging
+        # -T db2latex : different style
+        # -d : keep transient files (for debugging)
+        # -P abc.def=$quiet : once the stylesheets have a quiet mode
+        # -x "--path /path/to/more/files"
+        # xsltproc is already called with --xinclude
+        # does not work: --xslt-opts "--path $searchpath --nonet $@"
+        dblatex_options = ['-o', module + '.pdf']
+        for i in options.imgdir:
+            dblatex_options += ['-I', i]
+        if len(options.path):
+            dblatex_options += ['-x', '--path ' + ':'.join(options.path)]
+        dblatex_options.append(document)
+        if not options.verbose:
+            pc = subprocess.Popen([config.dblatex, '--help'], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            (stdo, stde) = pc.communicate()
+            if b'--quiet' in stdo or b'--quiet' in stde:
+                dblatex_options = ['--quiet'] + dblatex_options
+        dbcmd = [config.dblatex] + dblatex_options
+        pc = subprocess.Popen(dbcmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+        (stde, _) = pc.communicate()
+        for line in stde.decode('utf-8').split('\n'):
+            if not line.strip():
+                continue
+            if 'programlisting or screen' in line:
+                continue
+            # This happens when dblatex has no support for some special chars
+            if 'Missing character' in line:
+                continue
+            print(line)
+        res = pc.returncode
+    elif config.fop != '':
+        if options.verbose:
+            quiet = '0'
+        else:
+            quiet = '1'
+        res = run_xsltproc(options, ['--nonet',
+                                     '--xinclude',
+                                     '--stringparam',
+                                     'gtkdoc.bookname',
+                                     module,
+                                     '--stringparam',
+                                     'gtkdoc.version',
+                                     config.version,
+                                     '--stringparam',
+                                     'chunk.quietly',
+                                     quiet,
+                                     '--stringparam',
+                                     'chunker.output.quiet',
+                                     quiet,
+                                     module,
+                                     document,
+                                     '-o',
+                                     module + '.fo',
+                                     gtkdocdir + '/gtk-doc-fo.xsl',
+                                     document])
+        # TODO: fop dies too easily :(
+        # res = subprocess.call([config.fop, module + '.fo', module + '.pdf'))
+        fname = module + '.fo'
+        if os.path.exists(fname):
+            os.unlink(fname)
+    else:
+        print("dblatex or fop must be installed to use gtkdoc-mkpdf.")
+        res = 1
+
+    with open('pdf.stamp', 'w') as h:
+        h.write('timestamp')
+    return res
diff --git a/gtk-doc-for-gtk4/gtkdoc/rebase.py b/gtk-doc-for-gtk4/gtkdoc/rebase.py
new file mode 100755
index 0000000000..31a9b4ff9f
--- /dev/null
+++ b/gtk-doc-for-gtk4/gtkdoc/rebase.py
@@ -0,0 +1,253 @@
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998  Damon Chaplin
+#               2007  David Necas (Yeti)
+#               2007-2016  Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+"""
+The rebase tool rewrites URI references in installed HTML documentation.
+"""
+
+import logging
+import os
+import re
+
+from . import common
+
+# Maps.
+# These two point to the last seen URI of given type for a package:
+# OnlineMap: package => on-line URI
+# LocalMap: package => local URI
+# This maps all seen URIs of a package to fix broken links in the process:
+# RevMap: URI => package
+OnlineMap = {}
+LocalMap = {}
+RevMap = {}
+# Remember what mangling we did.
+Mapped = {}
+
+
+def log(options, *msg):
+    if options.verbose:
+        print(*msg)
+
+
+def run(options):
+    other_dirs = []
+
+    # We scan the directory containing GLib and any directories in GNOME2_PATH
+    # first, but these will be overridden by any later scans.
+    if "GNOME2_PATH" in os.environ:
+        for dir in os.environ["GNOME2_PATH"].split(':'):
+            dir = os.path.join(dir, "share/gtk-doc/html")
+            if os.path.isdir(dir):
+                log(options, "Prepending GNOME2_PATH directory:", dir)
+                other_dirs = [dir] + other_dirs
+
+    glib_dir = common.GetModuleDocDir('glib-2.0')
+    if glib_dir:
+        log(options, "Prepending GLib directory", glib_dir)
+        other_dirs = [glib_dir] + other_dirs
+
+    # Check all other dirs, but skip already scanned dirs ord subdirs of those
+
+    for dir in other_dirs:
+        ScanDirectory(dir, options)
+
+    if options.relative:
+        RelativizeLocalMap(options.html_dir, options)
+
+    RebaseReferences(options.html_dir, options)
+    PrintWhatWeHaveDone()
+
+
+def ScanDirectory(scan_dir, options):
+    log(options, "Scanning documentation directory %s", scan_dir)
+
+    if scan_dir == options.html_dir:
+        log(options, "Excluding self")
+        return
+
+    if not os.path.isdir(scan_dir):
+        logging.info('Cannot open dir "%s"', scan_dir)
+        return
+
+    subdirs = []
+    onlinedir = None
+    have_index = False
+    for entry in sorted(os.listdir(scan_dir)):
+        full_entry = os.path.join(scan_dir, entry)
+        if os.path.isdir(full_entry):
+            subdirs.append(full_entry)
+            continue
+
+        if entry.endswith('.devhelp2'):
+            log(options, "Reading index from " + entry)
+            o = ReadDevhelp(scan_dir, entry)
+            # Prefer this location over possibly stale index.sgml
+            if o is not None:
+                onlinedir = o
+            have_index = True
+
+        if onlinedir and entry == "index.sgml":
+            log(options, "Reading index from index.sgml")
+            onlinedir = ReadIndex(scan_dir, entry)
+            have_index = True
+        elif entry == "index.sgml.gz" and not os.path.exists(os.path.join(scan_dir, 'index.sgml')):
+            # debian/ubuntu started to compress this as index.sgml.gz :/
+            print(''' Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run:
+gunzip %s/%s
+''' % (scan_dir, entry))
+        elif entry.endswith('.devhelp2.gz') and not os.path.exists(full_entry[:-3]):
+            # debian/ubuntu started to compress this as *devhelp2.gz :/
+            print('''Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run:
+gunzip %s/%s
+''' % (scan_dir, entry))
+        # we could consider supporting: gzip module
+
+    if have_index:
+        AddMap(scan_dir, onlinedir, options)
+
+    # Now recursively scan the subdirectories.
+    for subdir in subdirs:
+        ScanDirectory(subdir, options)
+
+
+def ReadDevhelp(dir, file):
+    onlinedir = None
+
+    for line in open(os.path.join(dir, file), mode='r', encoding='utf-8'):
+        # online must come before chapter/functions
+        if '''', line)
+        if match:
+            # Remove trailing non-directory component.
+            onlinedir = re.sub(r'''(.*/).*''', r'\1', match.group(1))
+    return onlinedir
+
+
+def AddMap(dir, onlinedir, options):
+    package = None
+
+    package = os.path.split(dir)[1]
+    if options.dest_dir != '' and dir.startswith(options.dest_dir):
+        dir = dir[len(options.dest_dir) - 1:]
+
+    if onlinedir:
+        log(options, "On-line location of %s." % onlinedir)
+        OnlineMap[package] = onlinedir
+        RevMap[onlinedir] = package
+    else:
+        log(options, "No On-line location for %s found" % package)
+
+    log(options, "Local location of $package: " + dir)
+    LocalMap[package] = dir
+    RevMap[dir] = package
+
+
+def RelativizeLocalMap(dirname, options):
+    prefix = None
+    dir = None
+
+    dirname = os.path.realpath(dirname)
+    prefix = os.path.split(dirname)
+    for package, dir in LocalMap.items():
+        if dir.startswith(prefix):
+            dir = os.path.join("..", dir[len(prefix):])
+            LocalMap[package] = dir
+            log(options, "Relativizing local location of $package to " + dir)
+
+
+def RebaseReferences(dirname, options):
+    for ifile in sorted(os.listdir(dirname)):
+        if ifile.endswith('.html'):
+            RebaseFile(os.path.join(dirname, ifile), options)
+
+
+def RebaseFile(filename, options):
+    log(options, "Fixing file: " + filename)
+    regex = re.compile(r'''(", info[0], "(%s)" % info[1])
diff --git a/gtk-doc-for-gtk4/gtkdoc/scan.py b/gtk-doc-for-gtk4/gtkdoc/scan.py
new file mode 100644
index 0000000000..87809d27d4
--- /dev/null
+++ b/gtk-doc-for-gtk4/gtkdoc/scan.py
@@ -0,0 +1,1172 @@
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998  Damon Chaplin
+#               2007-2016  Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+"""
+Extracts declarations of functions, macros, enums, structs and unions from
+header files.
+
+It is called with a module name, an optional source directory, an optional
+output directory, and the header files to scan.
+
+It outputs all declarations found to a file named '$MODULE-decl.txt', and the
+list of decarations to another file '$MODULE-decl-list.txt'.
+
+This second list file is typically copied to '$MODULE-sections.txt' and
+organized into sections ready to output the XML pages.
+"""
+
+import logging
+import os
+import re
+import shutil
+
+from . import common
+
+TYPE_MODIFIERS = ['const', 'signed', 'unsigned', 'long', 'short', 'struct', 'union', 'enum']
+VAR_TYPE_MODIFIER = '(?:' + '|'.join([t + '\s+' for t in TYPE_MODIFIERS]) + ')*'
+RET_TYPE_MODIFIER = '(?:' + '|'.join([t + '\s+' for t in TYPE_MODIFIERS + ['G_CONST_RETURN']]) + ')*'
+
+# Matchers for current line
+CLINE_MATCHER = [
+    # 0: MACROS
+    re.compile(
+        r"""^\s*\#\s*define\s+
+        (\w+)               # 1: name
+        """, re.VERBOSE),
+    # 1-4: TYPEDEF'D FUNCTIONS
+    re.compile(
+        r"""^\s*typedef\s+
+        (%s\w+)                              # 1: return type
+        (\s+const)?\s*                       # 2: 2nd const
+        (\**)\s*                             # 3: ptr
+        \(\*\s*
+          (\w+)                              # 4: name
+        \)\s*\(""" % RET_TYPE_MODIFIER, re.VERBOSE),
+    re.compile(
+        r"""^\s*
+        (%s?\w+)                             # 1: return type
+        (\s+const)?\s*                       # 2: 2nd const
+        (\**)\s*                             # 3: ptr
+        \(\*\s*
+          (\w+)                              # 4: name
+        \)\s*\(""" % RET_TYPE_MODIFIER, re.VERBOSE),
+    re.compile(
+        r"""^\s*
+        (\**)\s*                             # 1: ptr
+        \(\*\s*
+          (\w+)                              # 2: name
+        \)\s*\(""", re.VERBOSE),
+    # 4: FUNCTION POINTER VARIABLES
+    None,  # in InitScanner()
+    # 5-7: ENUMS
+    re.compile(
+        r"""^\s*enum\s+
+        _?(\w+)                              # 1: name
+        \s+\{""", re.VERBOSE),
+    None,  # in InitScanner()
+    re.compile(r'^\s*typedef\s+enum'),
+    # 8-11: STRUCTS AND UNIONS
+    None,  # in InitScanner()
+    re.compile(r'^\s*(?:struct|union)\s+_(\w+)\s*;'),
+    re.compile(
+        r"""^\s*
+        (struct|union)\s+                    # 1: struct/union
+        (\w+)                                # 2: name
+        \s*;""", re.VERBOSE),
+    re.compile(
+        r"""^\s*typedef\s+
+        (struct|union)\s*
+        \w*\s*{""", re.VERBOSE),
+    # 12-14: OTHER TYPEDEFS
+    None,  # in InitScanner()
+    None,  # in InitScanner()
+    re.compile(r'^\s*typedef\s+'),
+    # 15: VARIABLES (extern'ed variables)
+    None,  # in InitScanner()
+    # 16: VARIABLES
+    re.compile(
+        r"""^\s*
+        (?:%s\w+)
+        (?:\s+\*+|\*+|\s)\s*
+        (?:const\s+)*
+        ([A-Za-z]\w*)                        # 1: name
+        \s*\=""" % VAR_TYPE_MODIFIER, re.VERBOSE),
+    # 17: G_DECLARE_*
+    re.compile(
+        r""".*(G_DECLARE_|GDK_DECLARE_)
+        (FINAL_TYPE|DERIVABLE_TYPE|INTERNAL_TYPE|INTERFACE) # 1: variant
+        \s*\(""", re.VERBOSE),
+    # 18-21: FUNCTIONS
+    None,  # in InitScanner()
+    None,  # in InitScanner()
+    re.compile(r'^\s*\(?([A-Za-z]\w*)\)?\s*\('),
+    re.compile(r'^\s*\('),
+    # 22-23: STRUCTS
+    re.compile(r'^\s*struct\s+_?(\w+)\s*\*'),
+    re.compile(r'^\s*struct\s+_?(\w+)'),
+    # 24-25: UNIONS
+    re.compile(r'^\s*union\s+_(\w+)\s*\*'),
+    re.compile(r'^\s*union\s+_?(\w+)'),
+]
+
+# Matchers for previous line
+PLINE_MATCHER = [
+    # 0-1: TYPEDEF'D FUNCTIONS
+    re.compile(
+        r"""^\s*typedef\s*
+        (%s\w+)                              # 1: return type
+        (\s+const)?\s*                       # 2: 2nd const
+        (\**)\s*                             # 3: ptr
+        """ % RET_TYPE_MODIFIER, re.VERBOSE),
+    re.compile(r'^\s*typedef\s*'),
+    # 2-4 :FUNCTIONS
+    None,  # in InitScanner()
+    None,  # in InitScanner()
+    None,  # in InitScanner()
+]
+
+# Matchers for 2nd previous line
+PPLINE_MATCHER = None
+
+# Matchers for sub expressions
+SUB_MATCHER = [
+    # 0: STRUCTS AND UNIONS
+    re.compile(r'^(\S+)(Class|Iface|Interface)\b'),
+]
+
+
+def Run(options):
+    logging.info('options: %s', str(options.__dict__))
+
+    InitScanner(options)
+
+    if not os.path.isdir(options.output_dir):
+        os.mkdir(options.output_dir)
+
+    base_filename = os.path.join(options.output_dir, options.module)
+    old_decl_list = base_filename + '-decl-list.txt'
+    new_decl_list = base_filename + '-decl-list.new'
+    old_decl = base_filename + '-decl.txt'
+    new_decl = base_filename + '-decl.new'
+    old_types = base_filename + '.types'
+    new_types = base_filename + '.types.new'
+    sections_file = base_filename + '-sections.txt'
+
+    # If this is the very first run then we create the .types file automatically.
+    if not os.path.exists(sections_file) and not os.path.exists(old_types):
+        options.rebuild_types = True
+
+    section_list = {}
+    decl_list = []
+    get_types = []
+
+    # do not read files twice; checking it here permits to give both srcdir and
+    # builddir as --source-dir without fear of duplicates
+    seen_headers = {}
+
+    # split all the ignored files and directories
+    ignored_headers = options.ignore_headers and options.ignore_headers.split(' ') or []
+
+    for file in options.headers:
+        # We assume that the specific headers we have been told to scan
+        # are not going to be placed in a blocklist
+        ScanHeader(file, section_list, decl_list, get_types, seen_headers, [], options)
+
+    for dir in options.source_dir:
+        # Ignored headers are relative to a source directory; since we
+        # pass the full path of each header to ScanHeader(), we need to
+        # build a list of absolute paths from the ignored headers list
+        src_ignored_headers = [os.path.join(dir, x) for x in ignored_headers]
+        ScanHeaders(dir, section_list, decl_list, get_types, seen_headers, src_ignored_headers, options)
+
+    with open(new_decl_list, 'w', encoding='utf-8') as f:
+        for section in sorted(section_list.keys()):
+            f.write(section_list[section])
+    common.UpdateFileIfChanged(old_decl_list, new_decl_list, True)
+
+    with open(new_decl, 'w', encoding='utf-8') as f:
+        for decl in decl_list:
+            f.write(decl)
+    common.UpdateFileIfChanged(old_decl, new_decl, True)
+
+    if options.rebuild_types:
+        with open(new_types, 'w', encoding='utf-8') as f:
+            for func in sorted(get_types):
+                f.write(func + '\n')
+
+        # remove the file if empty
+        if len(get_types) == 0:
+            os.unlink(new_types)
+            if os.path.exists(old_types):
+                os.rename(old_types, old_types + '.bak')
+        else:
+            common.UpdateFileIfChanged(old_types, new_types, True)
+
+    # If there is no MODULE-sections.txt file yet or we are asked to rebuild it,
+    # we copy the MODULE-decl-list.txt file into its place. The user can tweak it
+    # later if they want.
+    if options.rebuild_sections or not os.path.exists(sections_file):
+        new_sections_file = base_filename + '-sections.new'
+        shutil.copyfile(old_decl_list, new_sections_file)
+        common.UpdateFileIfChanged(sections_file, new_sections_file, False)
+
+    # If there is no MODULE-overrides.txt file we create an empty one
+    # because EXTRA_DIST in gtk-doc.make requires it.
+    overrides_file = base_filename + '-overrides.txt'
+    if not os.path.exists(overrides_file):
+        open(overrides_file, 'w', encoding='utf-8').close()
+
+
+def InitScanner(options):
+    """Apply options to regexps.
+    """
+
+    # avoid generating regex with |'' (matching no string)
+    # TODO(ensonic): keep in sync with ScanHeaderContent()
+    ignore_decorators = ''
+    optional_decorators_regex = ''
+    if options.ignore_decorators:
+        ignore_decorators = '|' + options.ignore_decorators.replace('()', '\(\w*\)')
+        optional_decorators_regex = '(?:\s+(?:%s))?' % ignore_decorators[1:]
+
+    # FUNCTION POINTER VARIABLES
+    CLINE_MATCHER[4] = re.compile(
+        r"""^\s*(?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+        ((?:const\s+|G_CONST_RETURN\s+)?\w+)           # 1: 1st const
+        (\s+const)?\s*                                 # 2: 2nd const
+        (\**)\s*                                       # 3: ptr
+        \(\*\s*
+          (\w+)                                        # 4: name
+        \)\s*\(""" % ignore_decorators, re.VERBOSE)
+
+    CLINE_MATCHER[6] = re.compile(r'^\s*typedef\s+enum\s+_?(\w+)\s+\1%s\s*;' % optional_decorators_regex)
+    CLINE_MATCHER[8] = re.compile(
+        r"""^\s*typedef\s+
+        (struct|union)\s+                    # 1: struct/union
+        _(\w+)\s+\2                          # 2: name
+        %s                                   # 3: optional decorator
+        \s*;""" % optional_decorators_regex, re.VERBOSE)
+    # OTHER TYPEDEFS
+    CLINE_MATCHER[12] = re.compile(
+        r"""^\s*typedef\s+
+        (?:struct|union)\s+\w+[\s\*]+
+        (\w+)                                # 1: name
+        %s                                   # 2: optional decorator
+        \s*;""" % optional_decorators_regex, re.VERBOSE)
+    CLINE_MATCHER[13] = re.compile(
+        r"""^\s*
+        (?:G_GNUC_EXTENSION\s+)?
+        typedef\s+
+        (.+?[\s\*])                          # 1: e.g. 'unsigned int'
+        (\w+)                                # 2: name
+        (?:\s*\[[^\]]+\])*
+        %s                                   # 3: optional decorator
+        \s*;""" % optional_decorators_regex, re.VERBOSE)
+    CLINE_MATCHER[15] = re.compile(
+        r"""^\s*
+        (?:extern|[A-Za-z_]+VAR%s)\s+
+        (?:%s\w+)
+        (?:\s+\*+|\*+|\s)\s*
+        (?:const\s+)*
+        ([A-Za-z]\w*)                                  # 1: name
+        \s*;""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+    # FUNCTIONS
+    CLINE_MATCHER[18] = re.compile(
+        r"""^\s*
+        (?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+        (%s\w+)                                                     # 1: return type
+        ([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*     # 2: .. cont'
+        (_[A-Za-z]\w*)                                              # 3: name
+        \s*\(""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+    CLINE_MATCHER[19] = re.compile(
+        r"""^\s*
+        (?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+        (%s\w+)                                                     # 1: return type
+        ([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*     # 2: .. cont'
+        \(?([A-Za-z]\w*)\)?                                         # 3: name
+        \s*\(""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+    PLINE_MATCHER[2] = re.compile(
+        r"""^\s*
+        (?:\b(?:extern%s)\s*)*
+        (%s\w+)                                                     # 1: retun type
+        ((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)              # 2: .. cont'
+        \s*$""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+    PLINE_MATCHER[3] = re.compile(
+        r"""^\s*(?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+        (%s\w+)                                                     # 1: return type
+        ((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)              # 2: .. cont'
+        \s*$""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+    PLINE_MATCHER[4] = re.compile(
+        r"""^\s*(?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+        (%s\w+)                                                     # 1: return type
+        (\s+\*+|\*+|\s)\s*                                          # 2: ptr?
+        ([A-Za-z]\w*)                                               # 3: symbols
+        \s*$""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+    # Matchers for 2nd previous line
+    global PPLINE_MATCHER
+    PPLINE_MATCHER = [
+        # 0: FUNCTIONS
+        re.compile(
+            r"""^\s*(?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+            (
+              (?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|struct\s+|union\s+|enum\s+)*
+              \w+
+              (?:\**\s+\**(?:const|G_CONST_RETURN))?
+              (?:\s+|\s*\*+)
+            )\s*$""" % ignore_decorators, re.VERBOSE)
+        ]
+
+
+def ScanHeaders(source_dir, section_list, decl_list, get_types, seen_headers, ignored_headers, options):
+    """Scans a directory tree looking for header files.
+
+    Args:
+      source_dir (str): the directory to scan.
+      section_list (dict): map of section to filenames.
+      decl_list (list): list of declarations
+      get_types (list): list of symbols that have a get_type function
+      seen_headers (set): set to avoid scanning headers twice
+      ignored_headers (list): list of ignored headers
+      options: command line options
+    """
+
+    logging.info('Scanning source directory: %s', source_dir)
+
+    # This array holds any subdirectories found.
+    subdirs = []
+
+    for filename in sorted(os.listdir(source_dir)):
+        if filename.startswith('.'):
+            continue
+        fullname = os.path.join(source_dir, filename)
+        if os.path.isdir(fullname):
+            subdirs.append(fullname)
+        elif filename.endswith('.h'):
+            if fullname in ignored_headers:
+                logging.info(f"File {fullname} matches ignored headers")
+                continue
+            ScanHeader(fullname, section_list, decl_list, get_types,
+                       seen_headers, ignored_headers, options)
+
+    # Now recursively scan the subdirectories.
+    for d in subdirs:
+        if d in ignored_headers:
+            logging.info(f"Directory {d} matches ignored headers")
+            continue
+        ScanHeaders(d, section_list, decl_list,
+                    get_types, seen_headers, ignored_headers, options)
+
+
+def ScanHeader(input_file, section_list, decl_list, get_types, seen_headers, ignored_headers, options):
+    """Scan a header file for doc commants.
+
+    Look for doc comments and extract them. Parse each doc comments and the
+    symbol declaration.
+
+    Args:
+      input_file (str): the header file to scan.
+      section_list (dict): a map of section per filename
+      decl_list (list): a list of declarations
+      get_types (list): list of symbols that have a get_type function
+      seen_headers (set): set to avoid scanning headers twice
+      ignored_headers (list): a list of ignored headers
+      options: command line options
+    """
+
+    # Skip ignored headers
+    if input_file in ignored_headers:
+        logging.info(f"File {input_file} matches ignored headers")
+        return
+
+    # Don't scan headers twice
+    canonical_input_file = os.path.realpath(input_file)
+    if canonical_input_file in seen_headers:
+        logging.info('File already scanned: %s', input_file)
+        return
+
+    seen_headers[canonical_input_file] = 1
+
+    file_basename = os.path.split(input_file)[1][:-2]  # filename ends in .h
+
+    if not os.path.exists(input_file):
+        logging.warning('File does not exist: %s', input_file)
+        return
+
+    logging.info('Scanning %s', input_file)
+
+    with open(input_file, 'r', encoding='utf-8') as hdr:
+        input_lines = hdr.readlines()
+
+    try:
+        slist, doc_comments = ScanHeaderContent(input_lines, decl_list, get_types, options)
+        logging.info("Scanning %s done", input_file)
+
+        liststr = SeparateSubSections(slist, doc_comments)
+        if liststr != '':
+            if file_basename not in section_list:
+                section_list[file_basename] = ''
+            section_list[file_basename] += "
    \n%s\n%s
    \n\n" % (file_basename, liststr)
+
+    except RuntimeError as e:
+        common.LogWarning(input_file, 0, str(e))
+
+
+def ScanHeaderContent(input_lines, decl_list, get_types, options):
+    """Scan the the given content lines.
+
+    Args:
+      input_lines (list):
+      decl_list (list): symbols declarations
+      get_types (list): list of symbols that have a get_type function
+      options: commandline options
+
+    Returns:
+      list: a list of symbols found and a set of symbols for which we have a
+            doc-comment
+    """
+
+    # Holds the resulting list of declarations.
+    slist = []
+    # Holds the title of the section
+    title = None
+    # True if we are in a comment.
+    in_comment = 0
+    # The type of declaration we are in, e.g. 'function' or 'macro'.
+    in_declaration = ''
+    # True if we should skip a block.
+    skip_block = False
+    # The current symbol being declared.
+    symbol = None
+    # Holds the declaration of the current symbol.
+    decl = ''
+    # For functions and function typedefs this holds the function's return type.
+    ret_type = None
+    # The pre-previous line read in - some Gnome functions have the return type
+    # on one line, the function name on the next, and the rest of the
+    # declaration after.
+    pre_previous_line = ''
+    # The previous line read in - some Gnome functions have the return type on
+    # one line and the rest of the declaration after.
+    previous_line = ''
+    # Used to try to skip the standard #ifdef XXX #define XXX at the start of
+    # headers.
+    first_macro = 1
+    # Used to handle structs/unions which contain nested structs or unions.
+    level = None
+    # Set to 1 for internal symbols, we need to fully parse, but don't add them
+    # to docs
+    internal = 0
+    # Dict of forward declarations, we skip them if we find the real declaration
+    # later.
+    forward_decls = {}
+    # Dict of doc-comments we found. The key is lowercase symbol name, val=1.
+    doc_comments = {}
+
+    deprecated_conditional_nest = 0
+    ignore_conditional_nest = 0
+
+    deprecated = ''
+    doc_comment = ''
+
+    # avoid generating regex with |'' (matching no string)
+    # TODO(ensonic): keep in sync with InitScanner()
+    # TODO(ensonic): extract the remaining regexps
+    ignore_decorators = ''          # 1 uses
+    optional_decorators_regex = ''  # 4 uses
+    if options.ignore_decorators:
+        ignore_decorators = '|' + options.ignore_decorators.replace('()', '\(\w*\)')
+        optional_decorators_regex = '(?:\s+(?:%s))?' % ignore_decorators[1:]
+
+    for line in input_lines:
+        # If this is a private header, skip it.
+        # TODO: consider scanning this first, so that we don't modify: decl_list
+        # and get_types
+        if re.search(r'^\s*/\*\s*<\s*private_header\s*>\s*\*/', line):
+            return [], {}
+
+        # Skip to the end of the current comment.
+        if in_comment:
+            logging.info('Comment: %s', line.strip())
+            doc_comment += line
+            if re.search(r'\*/', line):
+                m = re.search(r'\* ([a-zA-Z][a-zA-Z0-9_]+):', doc_comment)
+                if m:
+                    doc_comments[m.group(1).lower()] = 1
+                in_comment = 0
+                doc_comment = ''
+            continue
+
+        # Keep a count of #if, #ifdef, #ifndef nesting,
+        # and if we enter a deprecation-symbol-bracketed
+        # zone, take note.
+        m = re.search(r'^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)', line)
+        if m:
+            define_name = m.group(1)
+            if deprecated_conditional_nest < 1 and re.search(options.deprecated_guards, define_name):
+                deprecated_conditional_nest = 1
+            elif deprecated_conditional_nest >= 1:
+                deprecated_conditional_nest += 1
+            if ignore_conditional_nest == 0 and '__GTK_DOC_IGNORE__' in define_name:
+                ignore_conditional_nest = 1
+            elif ignore_conditional_nest > 0:
+                ignore_conditional_nest = 1
+
+        elif re.search(r'^\s*#\sif', line):
+            if deprecated_conditional_nest >= 1:
+                deprecated_conditional_nest += 1
+            if ignore_conditional_nest > 0:
+                ignore_conditional_nest += 1
+        elif re.search(r'^\s*#endif', line):
+            if deprecated_conditional_nest >= 1:
+                deprecated_conditional_nest -= 1
+            if ignore_conditional_nest > 0:
+                ignore_conditional_nest -= 1
+
+        # If we find a line containing _DEPRECATED, we hope that this is
+        # attribute based deprecation and also treat this as a deprecation
+        # guard, unless it's a macro definition or the end of a deprecation
+        # section (#endif /* XXX_DEPRECATED */
+        if deprecated_conditional_nest == 0 and '_DEPRECATED' in line:
+            m = re.search(r'^\s*#\s*(if*|define|endif)', line)
+            if not (m or in_declaration == 'enum' or in_declaration == 'struct'):
+                logging.info('Found deprecation annotation (decl: "%s"): "%s"',
+                             in_declaration, line.strip())
+                deprecated_conditional_nest += 0.1
+
+        # set flag that is used later when we do AddSymbolToList
+        if deprecated_conditional_nest > 0:
+            deprecated = '\n'
+        else:
+            deprecated = ''
+
+        if ignore_conditional_nest:
+            continue
+
+        if not in_declaration:
+            # Skip top-level comments.
+            m = re.search(r'^\s*/\*', line)
+            if m:
+                re.sub(r'^\s*/\*', '', line)
+                if re.search(r'\*/', line):
+                    logging.info('Found one-line comment: %s', line.strip())
+                else:
+                    in_comment = 1
+                    doc_comment = line
+                    logging.info('Found start of comment: %s', line.strip())
+                continue
+
+            # Skip begin/end deprecation macros.
+            m = re.search(r'^\s*G_GNUC_(BEGIN|END)_IGNORE_DEPRECATIONS', line)
+            if m:
+                continue
+
+            logging.info('no decl: %s', line.strip())
+
+            cm = [m.match(line) for m in CLINE_MATCHER]
+            pm = [m.match(previous_line) for m in PLINE_MATCHER]
+            ppm = [m.match(pre_previous_line) for m in PPLINE_MATCHER]
+
+            # MACROS
+
+            if cm[0]:
+                symbol = cm[0].group(1)
+                decl = line
+                # We assume all macros which start with '_' are private, but
+                # we accept '_' itself which is the standard gettext macro.
+                # We also try to skip the first macro if it looks like the
+                # standard #ifndef HEADER_FILE #define HEADER_FILE etc.
+                # And we only want TRUE & FALSE defined in GLib.
+                if not symbol.startswith('_') \
+                        and (not re.search(r'#ifndef\s+' + symbol, previous_line)
+                             or first_macro == 0) \
+                        and ((symbol != 'TRUE' and symbol != 'FALSE')
+                             or options.module == 'glib') \
+                        or symbol == '_':
+                    in_declaration = 'macro'
+                    logging.info('Macro: "%s"', symbol)
+                else:
+                    logging.info('skipping Macro: "%s"', symbol)
+                    in_declaration = 'macro'
+                    internal = 1
+                first_macro = 0
+
+            # TYPEDEF'D FUNCTIONS (i.e. user functions)
+            elif cm[1]:
+                ret_type = format_ret_type(cm[1].group(1), cm[1].group(2), cm[1].group(3))
+                symbol = cm[1].group(4)
+                decl = line[cm[1].end():]
+                in_declaration = 'user_function'
+                logging.info('user function (1): "%s", Returns: "%s"', symbol, ret_type)
+
+            elif pm[1] and cm[2]:
+                ret_type = format_ret_type(cm[2].group(1), cm[2].group(2), cm[2].group(3))
+                symbol = cm[2].group(4)
+                decl = line[cm[2].end():]
+                in_declaration = 'user_function'
+                logging.info('user function (2): "%s", Returns: "%s"', symbol, ret_type)
+
+            elif pm[1] and cm[3]:
+                ret_type = cm[3].group(1)
+                symbol = cm[3].group(2)
+                decl = line[cm[3].end():]
+                if pm[0]:
+                    ret_type = format_ret_type(pm[0].group(1), pm[0].group(2), pm[0].group(3)) + ret_type
+                    in_declaration = 'user_function'
+                    logging.info('user function (3): "%s", Returns: "%s"', symbol, ret_type)
+
+            # FUNCTION POINTER VARIABLES
+            elif cm[4]:
+                ret_type = format_ret_type(cm[4].group(1), cm[4].group(2), cm[4].group(3))
+                symbol = cm[4].group(4)
+                decl = line[cm[4].end():]
+                in_declaration = 'user_function'
+                logging.info('function pointer variable: "%s", Returns: "%s"', symbol, ret_type)
+
+            # ENUMS
+
+            elif cm[5]:
+                re.sub(r'^\s*enum\s+_?(\w+)\s+\{', r'enum \1 {', line)
+                # We assume that 'enum _ {' is really the
+                # declaration of enum .
+                symbol = cm[5].group(1)
+                decl = line
+                in_declaration = 'enum'
+                logging.info('plain enum: "%s"', symbol)
+
+            elif cm[6]:
+                # We skip 'typedef enum  _;' as the enum will
+                # be declared elsewhere.
+                logging.info('skipping enum typedef: "%s"', line)
+
+            elif cm[7]:
+                symbol = ''
+                decl = line
+                in_declaration = 'enum'
+                logging.info('typedef enum: -')
+
+            # STRUCTS AND UNIONS
+
+            elif cm[8]:
+                # We've found a 'typedef struct _ ;'
+                # This could be an opaque data structure, so we output an
+                # empty declaration. If the structure is actually found that
+                # will override this (technically if will just be another entry
+                # in the output file and will be joined when reading the file).
+                structsym = cm[8].group(1).upper()
+                logging.info('%s typedef: "%s"', structsym, cm[8].group(2))
+                forward_decls[cm[8].group(2)] = '<%s>\n%s\n%s\n' % (
+                    structsym, cm[8].group(2), deprecated, structsym)
+
+                m = SUB_MATCHER[0].match(cm[8].group(2))
+                if m:
+                    objectname = m.group(1)
+                    logging.info('Found object: "%s"', objectname)
+                    title = '%s' % objectname
+
+            elif cm[9]:
+                # Skip private structs/unions.
+                logging.info('private struct/union')
+
+            elif cm[10]:
+                # Do a similar thing for normal structs as for typedefs above.
+                # But we output the declaration as well in this case, so we
+                # can differentiate it from a typedef.
+                structsym = cm[10].group(1).upper()
+                logging.info('%s:%s', structsym, cm[10].group(2))
+                forward_decls[cm[10].group(2)] = '<%s>\n%s\n%s%s\n' % (
+                    structsym, cm[10].group(2), line, deprecated, structsym)
+
+            elif cm[11]:
+                symbol = ''
+                decl = line
+                level = 0
+                in_declaration = cm[11].group(1)
+                logging.info('typedef struct/union "%s"', in_declaration)
+
+            # OTHER TYPEDEFS
+
+            elif cm[12]:
+                logging.info('Found struct/union(*) typedef "%s": "%s"', cm[12].group(1), line)
+                if AddSymbolToList(slist, cm[12].group(1)):
+                    decl_list.append('\n%s\n%s%s\n' %
+                                     (cm[12].group(1), deprecated, line))
+
+            elif cm[13]:
+                if cm[13].group(1).split()[0] not in ('struct', 'union'):
+                    logging.info('Found typedef: "%s"', line)
+                    if AddSymbolToList(slist, cm[13].group(2)):
+                        decl_list.append(
+                            '\n%s\n%s%s\n' % (cm[13].group(2), deprecated, line))
+            elif cm[14]:
+                logging.info('Skipping typedef: "%s"', line)
+
+            # VARIABLES (extern'ed variables)
+
+            elif cm[15]:
+                symbol = cm[15].group(1)
+                line = re.sub(r'^\s*([A-Za-z_]+VAR)\b', r'extern', line)
+                decl = line
+                logging.info('Possible extern var "%s": "%s"', symbol, decl)
+                if AddSymbolToList(slist, symbol):
+                    decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, decl))
+
+            # VARIABLES
+
+            elif cm[16]:
+                symbol = cm[16].group(1)
+                decl = line
+                logging.info('Possible global var" %s": "%s"', symbol, decl)
+                if AddSymbolToList(slist, symbol):
+                    decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, decl))
+
+            # G_DECLARE_*
+
+            elif cm[17]:
+                in_declaration = 'g-declare'
+                symbol = cm[17].group(1) + cm[17].group(2)
+                decl = line[cm[17].end():]
+
+            # FUNCTIONS
+
+            elif cm[18]:
+                # We assume that functions starting with '_' are private and skip them.
+                ret_type = format_ret_type(cm[18].group(1), None, cm[18].group(2))
+                symbol = cm[18].group(3)
+                decl = line[cm[18].end():]
+                logging.info('internal Function: "%s", Returns: "%s""%s"', symbol, cm[18].group(1), cm[18].group(2))
+                in_declaration = 'function'
+                internal = 1
+                skip_block |= is_inline_func(line)
+
+            elif cm[19]:
+                ret_type = format_ret_type(cm[19].group(1), None, cm[19].group(2))
+                symbol = cm[19].group(3)
+                decl = line[cm[19].end():]
+                logging.info('Function (1): "%s", Returns: "%s""%s"', symbol, cm[19].group(1), cm[19].group(2))
+                in_declaration = 'function'
+                skip_block |= is_inline_func(line)
+
+            # Try to catch function declarations which have the return type on
+            # the previous line. But we don't want to catch complete functions
+            # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in
+            # glib, or 'static inline' functions.
+            elif cm[20]:
+                symbol = cm[20].group(1)
+                decl = line[cm[20].end():]
+
+                if is_inline_func(previous_line):
+                    skip_block = True
+                    if pm[3]:
+                        ret_type = format_ret_type(pm[3].group(1), None, pm[3].group(2))
+                        logging.info('Function  (3): "%s", Returns: "%s"', symbol, ret_type)
+                        in_declaration = 'function'
+                else:
+                    if pm[2]:
+                        ret_type = format_ret_type(pm[2].group(1), None, pm[2].group(2))
+                        logging.info('Function  (2): "%s", Returns: "%s"', symbol, ret_type)
+                        in_declaration = 'function'
+
+            # Try to catch function declarations with the return type and name
+            # on the previous line(s), and the start of the parameters on this.
+            elif cm[21]:
+                decl = line[cm[21].end():]
+                if pm[4]:
+                    ret_type = pm[4].group(1) + ' ' + pm[4].group(2).strip()
+                    symbol = pm[4].group(3)
+                    in_declaration = 'function'
+                    logging.info('Function (5): "%s", Returns: "%s"', symbol, ret_type)
+
+                elif re.search(r'^\s*\w+\s*$', previous_line) and ppm[0]:
+                    ret_type = ppm[0].group(1)
+                    ret_type = re.sub(r'\s*\n', '', ret_type, flags=re.MULTILINE)
+                    in_declaration = 'function'
+
+                    symbol = previous_line
+                    symbol = re.sub(r'^\s+', '', symbol)
+                    symbol = re.sub(r'\s*\n', '', symbol, flags=re.MULTILINE)
+                    logging.info('Function (6): "%s", Returns: "%s"', symbol, ret_type)
+
+            # } elsif (m/^extern\s+/) {
+                # print "DEBUG: Skipping extern: $_"
+
+            # STRUCTS
+            elif cm[22]:
+                # Skip 'struct _ *', since it could be a
+                # return type on its own line.
+                pass
+            elif cm[23]:
+                # We assume that 'struct _' is really the
+                # declaration of struct .
+                symbol = cm[23].group(1)
+                decl = line
+                # we will find the correct level as below we do $level += tr/{//
+                level = 0
+                in_declaration = 'struct'
+                logging.info('Struct(_): "%s"', symbol)
+
+            # UNIONS
+            elif cm[24]:
+                # Skip 'union _ *' (see above)
+                pass
+            elif cm[25]:
+                symbol = cm[25].group(1)
+                decl = line
+                level = 0
+                in_declaration = 'union'
+                logging.info('Union(_): "%s"', symbol)
+        else:
+            logging.info('in decl %s: skip=%s %s', in_declaration, skip_block, line.strip())
+            decl += line
+
+            if skip_block and '{' in decl:
+                (skip_block, decl) = remove_braced_content(decl)
+                logging.info('in decl: skip=%s decl=[%s]', skip_block, decl)
+
+        pre_previous_line = previous_line
+        previous_line = line
+
+        if skip_block:
+            logging.info('skipping, in decl %s, decl=[%s]', in_declaration, decl)
+            continue
+
+        if in_declaration == "g-declare":
+            dm = re.search(r'\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\).*$', decl)
+            # FIXME the original code does s// stuff here and we don't. Is it necessary?
+            if dm:
+                ModuleObjName = dm.group(1)
+                module_obj_name = dm.group(2)
+                if options.rebuild_types:
+                    get_types.append(module_obj_name + '_get_type')
+                forward_decls[ModuleObjName] = '\n%s\n%s\n' % (ModuleObjName, deprecated)
+                if symbol.startswith('G_DECLARE_DERIVABLE'):
+                    forward_decls[ModuleObjName + 'Class'] = '\n%sClass\n%s\n' % (
+                        ModuleObjName, deprecated)
+                if symbol.startswith('G_DECLARE_INTERFACE'):
+                    forward_decls[ModuleObjName + 'Interface'] = '\n%sInterface\n%s\n' % (
+                        ModuleObjName, deprecated)
+                in_declaration = ''
+
+        if in_declaration == 'function':
+            # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or
+            # ') __attribute__ (...);'.
+            regex = r'\)\s*(G_GNUC_.*|.*DEPRECATED.*%s\s*|__attribute__\s*\(.*\)\s*)*;.*$' % ignore_decorators
+            pm = re.search(regex, decl, flags=re.MULTILINE)
+            if pm:
+                logging.info('scrubbing:[%s]', decl.strip())
+                decl = re.sub(regex, '', decl, flags=re.MULTILINE)
+                logging.info('scrubbed:[%s]', decl.strip())
+                if internal == 0:
+                    decl = re.sub(r'/\*.*?\*/', '', decl, flags=re.MULTILINE)   # remove comments.
+                    decl = re.sub(r'\s*\n\s*(?!$)', ' ', decl, flags=re.MULTILINE)  # remove newlines
+                    # consolidate whitespace at start/end of lines.
+                    decl = decl.strip()
+                    ret_type = re.sub(r'/\*.*?\*/', '', ret_type).strip()       # remove comments in ret type.
+                    if AddSymbolToList(slist, symbol):
+                        decl_list.append('\n%s\n%s%s\n%s\n\n' %
+                                         (symbol, deprecated, ret_type, decl))
+                        if options.rebuild_types:
+                            # check if this looks like a get_type function and if so remember
+                            if symbol.endswith('_get_type') and 'GType' in ret_type and re.search(r'^(void|)$', decl):
+                                logging.info(
+                                    "Adding get-type: [%s] [%s] [%s]", ret_type, symbol, decl)
+                                get_types.append(symbol)
+                else:
+                    internal = 0
+                deprecated_conditional_nest = int(deprecated_conditional_nest)
+                in_declaration = ''
+                skip_block = False
+
+        if in_declaration == 'user_function':
+            if re.search(r'\).*$', decl):
+                decl = re.sub(r'\).*$', '', decl)
+                # TODO: same as above
+                decl = re.sub(r'/\*.*?\*/', '', decl, flags=re.MULTILINE)   # remove comments.
+                decl = re.sub(r'\s*\n\s*(?!$)', ' ', decl, flags=re.MULTILINE)  # remove newlines
+                # TODO: don't stip here (it works above, but fails some test
+                # consolidate whitespace at start/end of lines.
+                # decl = decl.strip()
+                if AddSymbolToList(slist, symbol):
+                    decl_list.append('\n%s\n%s%s\n%s\n' %
+                                     (symbol, deprecated, ret_type, decl))
+                deprecated_conditional_nest = int(deprecated_conditional_nest)
+                in_declaration = ''
+
+        if in_declaration == 'macro':
+            if not re.search(r'\\\s*$', decl):
+                if internal == 0:
+                    if AddSymbolToList(slist, symbol):
+                        decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, decl))
+                else:
+                    logging.info('skip internal macro: [%s]', symbol)
+                    internal = 0
+                deprecated_conditional_nest = int(deprecated_conditional_nest)
+                in_declaration = ''
+            else:
+                logging.info('skip empty macro: [%s]', symbol)
+
+        if in_declaration == 'enum':
+            # Examples:
+            # "};"
+            # "} MyEnum;"
+            # "} MyEnum DEPRECATED_FOR(NewEnum);"
+            # "} DEPRECATED_FOR(NewEnum);"
+            em = re.search(r'\n\s*\}\s*(?:(\w+)?%s)?;\s*$' % optional_decorators_regex, decl)
+            if em:
+                if symbol == '':
+                    symbol = em.group(1)
+                # Enums could contain deprecated values and that doesn't mean
+                # the whole enum is deprecated, so they are ignored when setting
+                # deprecated_conditional_nest above. Here we can check if the
+                # _DEPRECATED is between '}' and ';' which would mean the enum
+                # as a whole is deprecated.
+                if re.search(r'\n\s*\}.*_DEPRECATED.*;\s*$', decl):
+                    deprecated = '\n'
+                if AddSymbolToList(slist, symbol):
+                    stripped_decl = re.sub(optional_decorators_regex, '', decl)
+                    decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, stripped_decl))
+                deprecated_conditional_nest = int(deprecated_conditional_nest)
+                in_declaration = ''
+
+        # We try to handle nested structs/unions, but unmatched brackets in
+        # comments will cause problems.
+        if in_declaration == 'struct' or in_declaration == 'union':
+            # Same regex as for enum
+            sm = re.search(r'\n\}\s*(?:(\w+)?%s)?;\s*$' % optional_decorators_regex, decl)
+            if level <= 1 and sm:
+                if symbol == '':
+                    symbol = sm.group(1)
+
+                bm = re.search(r'^(\S+)(Class|Iface|Interface)\b', symbol)
+                if bm:
+                    objectname = bm.group(1)
+                    logging.info('Found object: "%s"', objectname)
+                    title = '%s' % objectname
+
+                logging.info('Store struct: "%s"', symbol)
+                # Structs could contain deprecated members and that doesn't
+                # mean the whole struct is deprecated, so they are ignored when
+                # setting deprecated_conditional_nest above. Here we can check
+                # if the _DEPRECATED is between '}' and ';' which would mean
+                # the struct as a whole is deprecated.
+                if re.search(r'\n\s*\}.*_DEPRECATED.*;\s*$', decl):
+                    deprecated = '\n'
+                if AddSymbolToList(slist, symbol):
+                    structsym = in_declaration.upper()
+                    regex = r'(?:\s+(?:G_GNUC_\w+(?:\(\w*\))?%s))' % ignore_decorators
+                    stripped_decl = re.sub(regex, '', decl)
+                    decl_list.append('<%s>\n%s\n%s%s\n' %
+                                     (structsym, symbol, deprecated, stripped_decl, structsym))
+                    if symbol in forward_decls:
+                        del forward_decls[symbol]
+                deprecated_conditional_nest = int(deprecated_conditional_nest)
+                in_declaration = ''
+            else:
+                # We use tr to count the brackets in the line, and adjust
+                # $level accordingly.
+                level += line.count('{')
+                level -= line.count('}')
+                logging.info('struct/union level : %d', level)
+
+    # here we want in_declaration=='', otherwise we have a partial declaration
+    if in_declaration != '':
+        raise RuntimeError('partial declaration (%s) : %s ' % (in_declaration, decl))
+
+    # print remaining forward declarations
+    for symbol in sorted(forward_decls.keys()):
+        if forward_decls[symbol]:
+            AddSymbolToList(slist, symbol)
+            decl_list.append(forward_decls[symbol])
+
+    # add title
+    if title:
+        slist = [title] + slist
+    return slist, doc_comments
+
+
+def remove_braced_content(decl):
+    """Remove all nested pairs of curly braces.
+
+    Args:
+      decl (str): the decl
+
+    Returns:
+      str: a declaration stripped of braced content
+    """
+
+    skip_block = True
+    # Remove all nested pairs of curly braces.
+    brace_remover = r'{[^{]*?}'
+    bm = re.search(brace_remover, decl)
+    while bm:
+        decl = re.sub(brace_remover, '', decl)
+        logging.info('decl=[%s]' % decl)
+        bm = re.search(brace_remover, decl)
+
+    # If all '{' have been matched and removed, we're done
+    bm = re.search(r'(.*?){', decl)
+    if not bm:
+        # this is a hack to detect the end of declaration
+        decl = decl.rstrip() + ';'
+        skip_block = False
+        logging.info('skip_block done')
+
+    return skip_block, decl
+
+
+def is_inline_func(line):
+    line = line.strip()
+    if line.startswith('G_INLINE_FUNC'):
+        logging.info('skip block after G_INLINE_FUNC function')
+        return True
+    if re.search(r'static\s+inline', line):
+        logging.info('skip block after static inline function')
+        return True
+    return False
+
+
+def format_ret_type(base_type, const, ptr):
+    ret_type = base_type
+    if const:
+        ret_type += const
+    if ptr:
+        ret_type += ' ' + ptr.strip()
+    return ret_type
+
+
+def SeparateSubSections(slist, doc_comments):
+    """Separate the standard macros and functions.
+
+    Place them at the end of the current section, in a subsection named
+    'Standard'. Do this in a loop to catch objects, enums and flags.
+
+    Args:
+      slist (list): list of symbols
+      doc_comments (dict): comments for each symbol
+
+    Returns:
+      str: the section doc xml fomatted as string
+    """
+
+    klass = lclass = prefix = lprefix = None
+    standard_decl = []
+    liststr = '\n'.join(s for s in slist if s) + '\n'
+    while True:
+        m = re.search(r'^(\S+)_IS_(\S*)_CLASS\n', liststr, flags=re.MULTILINE)
+        m2 = re.search(r'^(\S+)_IS_(\S*)\n', liststr, flags=re.MULTILINE)
+        m3 = re.search(r'^(\S+?)_(\S*)_get_type\n', liststr, flags=re.MULTILINE)
+        if m:
+            prefix = m.group(1)
+            lprefix = prefix.lower()
+            klass = m.group(2)
+            lclass = klass.lower()
+            logging.info("Found gobject type '%s_%s' from is_class macro", prefix, klass)
+        elif m2:
+            prefix = m2.group(1)
+            lprefix = prefix.lower()
+            klass = m2.group(2)
+            lclass = klass.lower()
+            logging.info("Found gobject type '%s_%s' from is_ macro", prefix, klass)
+        elif m3:
+            lprefix = m3.group(1)
+            prefix = lprefix.upper()
+            lclass = m3.group(2)
+            klass = lclass.upper()
+            logging.info("Found gobject type '%s_%s' from get_type function", prefix, klass)
+        else:
+            break
+
+        cclass = lclass
+        cclass = cclass.replace('_', '')
+        mtype = lprefix + cclass
+
+        liststr, standard_decl = replace_once(liststr, standard_decl, r'^%sPrivate\n' % mtype)
+
+        # We only leave XxYy* in the normal section if they have docs
+        if mtype not in doc_comments:
+            logging.info("  Hide instance docs for %s", mtype)
+            liststr, standard_decl = replace_once(liststr, standard_decl, r'^%s\n' % mtype)
+
+        if mtype + 'class' not in doc_comments:
+            logging.info("  Hide class docs for %s", mtype)
+            liststr, standard_decl = replace_once(liststr, standard_decl, r'^%sClass\n' % mtype)
+
+        if mtype + 'interface' not in doc_comments:
+            logging.info("  Hide iface docs for %s", mtype)
+            liststr, standard_decl = replace_once(liststr, standard_decl, r'%sInterface\n' % mtype)
+
+        if mtype + 'iface' not in doc_comments:
+            logging.info("  Hide iface docs for " + mtype)
+            liststr, standard_decl = replace_once(liststr, standard_decl, r'%sIface\n' % mtype)
+
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_IS_%s\n' % klass)
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_TYPE_%s\n' % klass)
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_get_type\n' % lclass)
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_IS_%s_CLASS\n' % klass)
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_CLASS\n' % klass)
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_CLASS\n' % klass)
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_IFACE\n' % klass)
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_INTERFACE\n' % klass)
+        # We do this one last, otherwise it tends to be caught by the IS_$class macro
+        liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s\n' % klass)
+
+    logging.info('Decl:%s---', liststr)
+    logging.info('Std :%s---', ''.join(sorted(standard_decl)))
+    if len(standard_decl):
+        # sort the symbols
+        liststr += '\n' + ''.join(sorted(standard_decl))
+    return liststr
+
+
+def replace_once(liststr, standard_decl, regex):
+    mre = re.search(regex, liststr,  flags=re.IGNORECASE | re.MULTILINE)
+    if mre:
+        standard_decl.append(mre.group(0))
+        liststr = re.sub(regex, '', liststr, flags=re.IGNORECASE | re.MULTILINE)
+    return liststr, standard_decl
+
+
+def replace_all(liststr, standard_decl, regex):
+    mre = re.search(regex, liststr, flags=re.MULTILINE)
+    while mre:
+        standard_decl.append(mre.group(0))
+        liststr = re.sub(regex, '', liststr, flags=re.MULTILINE)
+        mre = re.search(regex, liststr, flags=re.MULTILINE)
+    return liststr, standard_decl
+
+
+def AddSymbolToList(slist, symbol):
+    """ Adds symbol to list of declaration if not already present.
+
+    Args:
+        slist: The list of symbols.
+        symbol: The symbol to add to the list.
+    """
+    if symbol in slist:
+        # logging.info('Symbol %s already in list. skipping', symbol)
+        # we return False to skip outputting another entry to -decl.txt
+        # this is to avoid redeclarations (e.g. in conditional sections).
+        return False
+    slist.append(symbol)
+    return True
diff --git a/gtk-doc-for-gtk4/gtkdoc/scangobj.py b/gtk-doc-for-gtk4/gtkdoc/scangobj.py
new file mode 100644
index 0000000000..0069c0a1ad
--- /dev/null
+++ b/gtk-doc-for-gtk4/gtkdoc/scangobj.py
@@ -0,0 +1,1418 @@
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998  Damon Chaplin
+#               2007-2016  Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+"""
+The scangobj tool gets information about object hierarchies and signals by
+compiling and running a small C program. CFLAGS and LDFLAGS must be set
+appropriately before running this script.
+"""
+
+import logging
+import os
+import string
+import subprocess
+import shlex
+
+from . import common, config
+
+
+COMMON_INCLUDES = """
+#include 
+#include 
+#include 
+#include 
+#include 
+"""
+
+QUERY_CHILD_PROPS_PROTOTYPE = "extern GParamSpec** %s (gpointer class, guint *n_properties);"
+
+QUERY_CHILD_PROPS_CODE = """
+    if (!child_prop) {
+      properties = %s (class, &n_properties);
+      if (properties) {
+        child_prop = TRUE;
+        continue;
+      }
+   }
+"""
+
+MAIN_CODE = """
+
+#ifdef GTK_IS_WIDGET_CLASS
+#include 
+#endif
+static GType object_types[${ntypes}];
+
+static GType *
+get_object_types (void)
+{
+  gpointer g_object_class;
+  gint i = 0;
+
+${get_types}
+  object_types[i] = G_TYPE_INVALID;
+
+  /* reference the GObjectClass to initialize the param spec pool
+   * potentially needed by interfaces. See http://bugs.gnome.org/571820 */
+  g_object_class = g_type_class_ref (G_TYPE_OBJECT);
+
+  /* Need to make sure all the types are loaded in and initialize
+   * their signals and properties.
+   */
+  for (i=0; object_types[i]; i++) {
+    if (G_TYPE_IS_CLASSED (object_types[i]))
+      g_type_class_ref (object_types[i]);
+    if (G_TYPE_IS_INTERFACE (object_types[i]))
+      g_type_default_interface_ref (object_types[i]);
+  }
+
+  g_type_class_unref (g_object_class);
+
+  return object_types;
+}
+
+/*
+ * This uses GObject type functions to output signal prototypes and the object
+ * hierarchy.
+ */
+
+/* The output files */
+const gchar *signals_filename = "${new_signals_filename}";
+const gchar *hierarchy_filename = "${new_hierarchy_filename}";
+const gchar *interfaces_filename = "${new_interfaces_filename}";
+const gchar *prerequisites_filename = "${new_prerequisites_filename}";
+const gchar *args_filename = "${new_args_filename}";
+const gchar *actions_filename = "${new_actions_filename}";
+
+static void output_signals (void);
+static void output_object_signals (FILE *fp,
+                                   GType object_type);
+static void output_object_signal (FILE *fp,
+                                  const gchar *object_class_name,
+                                  guint signal_id);
+static const gchar * get_type_name (GType type,
+                                    gboolean * is_pointer);
+static void output_object_hierarchy (void);
+static void output_hierarchy (FILE *fp,
+                              GType type,
+                              guint level);
+
+static void output_object_interfaces (void);
+static void output_interfaces (FILE *fp,
+                               GType type);
+
+static void output_interface_prerequisites (void);
+static void output_prerequisites (FILE *fp,
+                                  GType type);
+
+static void output_args (void);
+static void output_object_args (FILE *fp, GType object_type);
+
+static void output_actions (void);
+static void output_object_actions (FILE *fp, GType object_type);
+
+int
+main (${main_func_params})
+{
+  ${type_init_func};
+
+  get_object_types ();
+
+  output_signals ();
+  output_object_hierarchy ();
+  output_object_interfaces ();
+  output_interface_prerequisites ();
+  output_args ();
+  output_actions ();
+
+  return 0;
+}
+
+static void
+output_signals (void)
+{
+  FILE *fp;
+  gint i;
+
+  fp = fopen (signals_filename, "w");
+  if (fp == NULL) {
+    g_warning ("Couldn't open output file: %s : %s", signals_filename, g_strerror(errno));
+    return;
+  }
+
+  for (i = 0; object_types[i]; i++)
+    output_object_signals (fp, object_types[i]);
+
+  fclose (fp);
+}
+
+static gint
+compare_signals (const void *a, const void *b)
+{
+  const guint *signal_a = a;
+  const guint *signal_b = b;
+
+  return strcmp (g_signal_name (*signal_a), g_signal_name (*signal_b));
+}
+
+/* This outputs all the signals of one object. */
+static void
+output_object_signals (FILE *fp, GType object_type)
+{
+  const gchar *object_class_name;
+  guint *signals, n_signals;
+  guint sig;
+
+  if (G_TYPE_IS_INSTANTIATABLE (object_type) ||
+      G_TYPE_IS_INTERFACE (object_type)) {
+
+    object_class_name = g_type_name (object_type);
+
+    signals = g_signal_list_ids (object_type, &n_signals);
+    qsort (signals, n_signals, sizeof (guint), compare_signals);
+
+    for (sig = 0; sig < n_signals; sig++) {
+       output_object_signal (fp, object_class_name, signals[sig]);
+    }
+    g_free (signals);
+  }
+}
+
+/* This outputs one signal. */
+static void
+output_object_signal (FILE *fp,
+                      const gchar *object_name,
+                      guint signal_id)
+{
+  GSignalQuery query_info;
+  const gchar *type_name, *ret_type, *object_arg, *arg_name;
+  gchar *pos, *object_arg_lower;
+  gboolean is_pointer;
+  gchar buffer[1024];
+  guint i, param;
+  gint param_num, widget_num, event_num, callback_num;
+  gint *arg_num;
+  gchar signal_name[128];
+  gchar flags[16];
+
+  /*  g_print ("Object: %s Signal: %u\\n", object_name, signal_id);*/
+
+  param_num = 1;
+  widget_num = event_num = callback_num = 0;
+
+  g_signal_query (signal_id, &query_info);
+
+  /* Output the signal object type and the argument name. We assume the
+   * type is a pointer - I think that is OK. We remove "Gtk" or "Gnome" and
+   * convert to lower case for the argument name. */
+  pos = buffer;
+  sprintf (pos, "%s ", object_name);
+  pos += strlen (pos);
+
+  /* Try to come up with a sensible variable name for the first arg
+   * It chops off 2 know prefixes :/ and makes the name lowercase
+   * It should replace lowercase -> uppercase with '_'
+   * GFileMonitor -> file_monitor
+   * GIOExtensionPoint -> extension_point
+   * GtkTreeView -> tree_view
+   * if 2nd char is upper case too
+   *   search for first lower case and go back one char
+   * else
+   *   search for next upper case
+   */
+  if (!strncmp (object_name, "Gtk", 3))
+    object_arg = object_name + 3;
+  else if (!strncmp (object_name, "Gnome", 5))
+    object_arg = object_name + 5;
+  else
+    object_arg = object_name;
+
+  object_arg_lower = g_ascii_strdown (object_arg, -1);
+  sprintf (pos, "*%s\\n", object_arg_lower);
+  pos += strlen (pos);
+  if (!strncmp (object_arg_lower, "widget", 6))
+    widget_num = 2;
+  g_free(object_arg_lower);
+
+  /* Convert signal name to use underscores rather than dashes '-'. */
+  strncpy (signal_name, query_info.signal_name, 127);
+  signal_name[127] = '\\0';
+  for (i = 0; signal_name[i]; i++) {
+    if (signal_name[i] == '-')
+      signal_name[i] = '_';
+  }
+
+  /* Output the signal parameters. */
+  for (param = 0; param < query_info.n_params; param++) {
+    type_name = get_type_name (query_info.param_types[param] & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
+
+    /* Most arguments to the callback are called "arg1", "arg2", etc.
+       GtkWidgets are called "widget", "widget2", ...
+       GtkCallbacks are called "callback", "callback2", ... */
+    if (!strcmp (type_name, "GtkWidget")) {
+      arg_name = "widget";
+      arg_num = &widget_num;
+    }
+    else if (!strcmp (type_name, "GtkCallback")
+             || !strcmp (type_name, "GtkCCallback")) {
+      arg_name = "callback";
+      arg_num = &callback_num;
+    }
+    else {
+      arg_name = "arg";
+      arg_num = ¶m_num;
+    }
+    sprintf (pos, "%s ", type_name);
+    pos += strlen (pos);
+
+    if (!arg_num || *arg_num == 0)
+      sprintf (pos, "%s%s\\n", is_pointer ? "*" : " ", arg_name);
+    else
+      sprintf (pos, "%s%s%i\\n", is_pointer ? "*" : " ", arg_name,
+               *arg_num);
+    pos += strlen (pos);
+
+    if (arg_num) {
+      if (*arg_num == 0)
+        *arg_num = 2;
+      else
+        *arg_num += 1;
+    }
+  }
+
+  pos = flags;
+  /* We use one-character flags for simplicity. */
+  if (query_info.signal_flags & G_SIGNAL_RUN_FIRST)
+    *pos++ = 'f';
+  if (query_info.signal_flags & G_SIGNAL_RUN_LAST)
+    *pos++ = 'l';
+  if (query_info.signal_flags & G_SIGNAL_RUN_CLEANUP)
+    *pos++ = 'c';
+  if (query_info.signal_flags & G_SIGNAL_NO_RECURSE)
+    *pos++ = 'r';
+  if (query_info.signal_flags & G_SIGNAL_DETAILED)
+    *pos++ = 'd';
+  if (query_info.signal_flags & G_SIGNAL_ACTION)
+    *pos++ = 'a';
+  if (query_info.signal_flags & G_SIGNAL_NO_HOOKS)
+    *pos++ = 'h';
+  *pos = 0;
+
+  /* Output the return type and function name. */
+  ret_type = get_type_name (query_info.return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
+
+  fprintf (fp,
+           "\\n%s::%s\\n%s%s\\n%s\\n%s\\n\\n",
+           object_name, query_info.signal_name, ret_type, is_pointer ? "*" : "", flags, buffer);
+}
+
+
+/* Returns the type name to use for a signal argument or return value, given
+   the GtkType from the signal info. It also sets is_pointer to TRUE if the
+   argument needs a '*' since it is a pointer. */
+static const gchar *
+get_type_name (GType type, gboolean * is_pointer)
+{
+  const gchar *type_name;
+
+  *is_pointer = FALSE;
+  type_name = g_type_name (type);
+
+  switch (type) {
+  case G_TYPE_NONE:
+  case G_TYPE_UCHAR:
+  case G_TYPE_BOOLEAN:
+  case G_TYPE_UINT:
+  case G_TYPE_LONG:
+  case G_TYPE_ULONG:
+  case G_TYPE_POINTER:
+    /* These all have normal C type names so they are OK. */
+    return type_name;
+
+  case G_TYPE_CHAR:
+    return "char";
+
+  case G_TYPE_INT:
+    return "int";
+
+  case G_TYPE_FLOAT:
+    return "float";
+
+  case G_TYPE_DOUBLE:
+    return "double";
+
+  case G_TYPE_STRING:
+    /* A GtkString is really a gchar*. */
+    *is_pointer = TRUE;
+    return "char";
+
+  case G_TYPE_ENUM:
+  case G_TYPE_FLAGS:
+    /* We use a gint for both of these. Hopefully a subtype with a decent
+       name will be registered and used instead, as GTK+ does itself. */
+    return "int";
+
+  case G_TYPE_BOXED:
+    /* The boxed type shouldn't be used itself, only subtypes. Though we
+       return 'gpointer' just in case. */
+    return "gpointer";
+
+  case G_TYPE_PARAM:
+    /* A GParam is really a GParamSpec*. */
+    *is_pointer = TRUE;
+    return "GParamSpec";
+
+#if GLIB_CHECK_VERSION (2, 25, 9)
+  case G_TYPE_VARIANT:
+    *is_pointer = TRUE;
+    return "GVariant";
+#endif
+
+default:
+    break;
+  }
+
+  /* For all GObject subclasses we can use the class name with a "*",
+     e.g. 'GtkWidget *'. */
+  if (g_type_is_a (type, G_TYPE_OBJECT))
+    *is_pointer = TRUE;
+
+  /* Also catch non GObject root types */
+  if (G_TYPE_IS_CLASSED (type))
+    *is_pointer = TRUE;
+
+  /* All boxed subtypes will be pointers as well. */
+  /* Exception: GStrv */
+  if (g_type_is_a (type, G_TYPE_BOXED) &&
+      !g_type_is_a (type, G_TYPE_STRV))
+    *is_pointer = TRUE;
+
+  /* All pointer subtypes will be pointers as well. */
+  if (g_type_is_a (type, G_TYPE_POINTER))
+    *is_pointer = TRUE;
+
+  /* But enums are not */
+  if (g_type_is_a (type, G_TYPE_ENUM) ||
+      g_type_is_a (type, G_TYPE_FLAGS))
+    *is_pointer = FALSE;
+
+  return type_name;
+}
+
+
+/* This outputs the hierarchy of all objects which have been initialized,
+   i.e. by calling their XXX_get_type() initialization function. */
+static void
+output_object_hierarchy (void)
+{
+  FILE *fp;
+  gint i,j;
+  GType root, type;
+  GType root_types[${ntypes}] = { G_TYPE_INVALID, };
+
+  fp = fopen (hierarchy_filename, "w");
+  if (fp == NULL) {
+    g_warning ("Couldn't open output file: %s : %s", hierarchy_filename, g_strerror(errno));
+    return;
+  }
+  output_hierarchy (fp, G_TYPE_OBJECT, 0);
+  output_hierarchy (fp, G_TYPE_INTERFACE, 0);
+
+  for (i=0; object_types[i]; i++) {
+    root = object_types[i];
+    while ((type = g_type_parent (root))) {
+      root = type;
+    }
+    if ((root != G_TYPE_OBJECT) && (root != G_TYPE_INTERFACE)) {
+      for (j=0; root_types[j]; j++) {
+        if (root == root_types[j]) {
+          root = G_TYPE_INVALID; break;
+        }
+      }
+      if(root) {
+        root_types[j] = root;
+        output_hierarchy (fp, root, 0);
+      }
+    }
+  }
+
+  fclose (fp);
+}
+
+/* This is called recursively to output the hierarchy of a object. */
+static void
+output_hierarchy (FILE  *fp,
+                  GType  type,
+                  guint   level)
+{
+  guint i;
+  GType *children;
+  guint n_children;
+
+  if (!type)
+    return;
+
+  for (i = 0; i < level; i++)
+    fprintf (fp, "  ");
+  fprintf (fp, "%s\\n", g_type_name (type));
+
+  children = g_type_children (type, &n_children);
+
+  for (i=0; i < n_children; i++)
+    output_hierarchy (fp, children[i], level + 1);
+
+  g_free (children);
+}
+
+static void output_object_interfaces (void)
+{
+  guint i;
+  FILE *fp;
+
+  fp = fopen (interfaces_filename, "w");
+  if (fp == NULL) {
+    g_warning ("Couldn't open output file: %s : %s", interfaces_filename, g_strerror(errno));
+    return;
+  }
+  output_interfaces (fp, G_TYPE_OBJECT);
+
+  for (i = 0; object_types[i]; i++) {
+    if (!g_type_parent (object_types[i]) &&
+        (object_types[i] != G_TYPE_OBJECT) &&
+        G_TYPE_IS_INSTANTIATABLE (object_types[i])) {
+      output_interfaces (fp, object_types[i]);
+    }
+  }
+  fclose (fp);
+}
+
+static void
+output_interfaces (FILE  *fp,
+                   GType  type)
+{
+  guint i;
+  GType *children, *interfaces;
+  guint n_children, n_interfaces;
+
+  if (!type)
+    return;
+
+  interfaces = g_type_interfaces (type, &n_interfaces);
+
+  if (n_interfaces > 0) {
+    fprintf (fp, "%s", g_type_name (type));
+    for (i=0; i < n_interfaces; i++)
+        fprintf (fp, " %s", g_type_name (interfaces[i]));
+    fprintf (fp, "\\n");
+   }
+  g_free (interfaces);
+
+  children = g_type_children (type, &n_children);
+
+  for (i=0; i < n_children; i++)
+    output_interfaces (fp, children[i]);
+
+  g_free (children);
+}
+
+static void output_interface_prerequisites (void)
+{
+  FILE *fp;
+
+  fp = fopen (prerequisites_filename, "w");
+  if (fp == NULL) {
+    g_warning ("Couldn't open output file: %s : %s", prerequisites_filename, g_strerror(errno));
+    return;
+  }
+  output_prerequisites (fp, G_TYPE_INTERFACE);
+  fclose (fp);
+}
+
+static void
+output_prerequisites (FILE  *fp,
+                      GType  type)
+{
+#if GLIB_CHECK_VERSION(2,1,0)
+  guint i;
+  GType *children, *prerequisites;
+  guint n_children, n_prerequisites;
+
+  if (!type)
+    return;
+
+  prerequisites = g_type_interface_prerequisites (type, &n_prerequisites);
+
+  if (n_prerequisites > 0) {
+    fprintf (fp, "%s", g_type_name (type));
+    for (i=0; i < n_prerequisites; i++)
+        fprintf (fp, " %s", g_type_name (prerequisites[i]));
+    fprintf (fp, "\\n");
+   }
+  g_free (prerequisites);
+
+  children = g_type_children (type, &n_children);
+
+  for (i=0; i < n_children; i++)
+    output_prerequisites (fp, children[i]);
+
+  g_free (children);
+#endif
+}
+
+static void
+output_actions (void)
+{
+  FILE *fp;
+  gint i;
+
+  fp = fopen (actions_filename, "w");
+  if (fp == NULL) {
+    g_warning ("Couldn't open output file: %s : %s", actions_filename, g_strerror(errno));
+    return;
+  }
+
+  for (i = 0; object_types[i]; i++) {
+    output_object_actions (fp, object_types[i]);
+  }
+
+  fclose (fp);
+}
+
+static void
+output_object_actions (FILE *fp, GType object_type)
+{
+  gpointer class;
+
+  if (!G_TYPE_IS_OBJECT (object_type))
+    return;
+
+  class = g_type_class_peek (object_type);
+  if (!class)
+    return;
+
+#ifdef GTK_IS_WIDGET_CLASS
+#if GTK_CHECK_VERSION(3,96,0)
+  if (GTK_IS_WIDGET_CLASS (class)) {
+    guint i = 0;
+    const char *action_name;
+    GType owner;
+    const GVariantType *parameter_type;
+    const char *property_name;
+    const gchar *object_class_name;
+
+    object_class_name = g_type_name (object_type);
+    while (gtk_widget_class_query_action (GTK_WIDGET_CLASS (class),
+                                          i,
+                                          &owner,
+                                          &action_name,
+                                          ¶meter_type,
+                                          &property_name)) {
+      i++;
+      if (owner == G_TYPE_FROM_CLASS (class))
+        fprintf (fp, "\\n"
+                     "%s:::%s\\n"
+                     "%s\\n"
+                     "%s\\n"
+                     "\\n\\n",
+                 object_class_name,
+                 action_name,
+                 parameter_type ? g_variant_type_peek_string (parameter_type) : "",
+                 property_name ? property_name : "");
+    }
+  }
+#endif
+#endif
+}
+
+static void
+output_args (void)
+{
+  FILE *fp;
+  gint i;
+
+  fp = fopen (args_filename, "w");
+  if (fp == NULL) {
+    g_warning ("Couldn't open output file: %s : %s", args_filename, g_strerror(errno));
+    return;
+  }
+
+  for (i = 0; object_types[i]; i++) {
+    output_object_args (fp, object_types[i]);
+  }
+
+  fclose (fp);
+}
+
+static gint
+compare_param_specs (const void *a, const void *b)
+{
+  GParamSpec *spec_a = *(GParamSpec **)a;
+  GParamSpec *spec_b = *(GParamSpec **)b;
+
+  return strcmp (g_param_spec_get_name (spec_a), g_param_spec_get_name (spec_b));
+}
+
+/* Its common to have unsigned properties restricted
+ * to the signed range. Therefore we make this look
+ * a bit nicer by spelling out the max constants.
+ */
+
+/* Don't use "==" with floats, it might trigger a gcc warning.  */
+#define GTKDOC_COMPARE_FLOAT(x, y) (x <= y && x >= y)
+
+static gchar*
+describe_double_constant (gdouble value)
+{
+  gchar *desc;
+
+  if (GTKDOC_COMPARE_FLOAT (value, G_MAXDOUBLE))
+    desc = g_strdup ("G_MAXDOUBLE");
+  else if (GTKDOC_COMPARE_FLOAT (value, G_MINDOUBLE))
+    desc = g_strdup ("G_MINDOUBLE");
+  else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXDOUBLE))
+    desc = g_strdup ("-G_MAXDOUBLE");
+  else if (GTKDOC_COMPARE_FLOAT (value, (gdouble)G_MAXFLOAT))
+    desc = g_strdup ("G_MAXFLOAT");
+  else if (GTKDOC_COMPARE_FLOAT (value, (gdouble)G_MINFLOAT))
+    desc = g_strdup ("G_MINFLOAT");
+  else if (GTKDOC_COMPARE_FLOAT (value, (gdouble)-G_MAXFLOAT))
+    desc = g_strdup ("-G_MAXFLOAT");
+  else{
+    /* make sure floats are output with a decimal dot irrespective of
+    * current locale. Use formatd since we want human-readable numbers
+    * and do not need the exact same bit representation when deserialising */
+    desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
+    g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", value);
+  }
+
+  return desc;
+}
+
+static gchar*
+describe_signed_constant (gsize size, gint64 value)
+{
+  gchar *desc = NULL;
+
+  switch (size) {
+    case 2:
+      if (sizeof (int) == 2) {
+        if (value == G_MAXINT)
+          desc = g_strdup ("G_MAXINT");
+        else if (value == G_MININT)
+          desc = g_strdup ("G_MININT");
+      }
+      break;
+    case 4:
+      if (sizeof (int) == 4) {
+        if (value == G_MAXINT)
+          desc = g_strdup ("G_MAXINT");
+        else if (value == G_MININT)
+          desc = g_strdup ("G_MININT");
+      }
+      if (value == G_MAXLONG)
+        desc = g_strdup ("G_MAXLONG");
+      else if (value == G_MINLONG)
+        desc = g_strdup ("G_MINLONG");
+      break;
+    case 8:
+      if (value == G_MAXINT64)
+        desc = g_strdup ("G_MAXINT64");
+      else if (value == G_MININT64)
+        desc = g_strdup ("G_MININT64");
+      break;
+    default:
+      break;
+  }
+  if (!desc)
+    desc = g_strdup_printf ("%" G_GINT64_FORMAT, value);
+
+  return desc;
+}
+
+static gchar*
+describe_unsigned_constant (gsize size, guint64 value)
+{
+  gchar *desc = NULL;
+
+  switch (size) {
+    case 2:
+      if (sizeof (int) == 2) {
+        if (value == (guint64)G_MAXINT)
+          desc = g_strdup ("G_MAXINT");
+        else if (value == G_MAXUINT)
+          desc = g_strdup ("G_MAXUINT");
+      }
+      break;
+    case 4:
+      if (sizeof (int) == 4) {
+        if (value == (guint64)G_MAXINT)
+          desc = g_strdup ("G_MAXINT");
+        else if (value == G_MAXUINT)
+          desc = g_strdup ("G_MAXUINT");
+      }
+      if (desc == NULL) {
+        if (value == (guint64)G_MAXLONG)
+          desc = g_strdup ("G_MAXLONG");
+        else if (value == G_MAXULONG)
+          desc = g_strdup ("G_MAXULONG");
+      }
+      break;
+    case 8:
+      if (value == G_MAXINT64)
+        desc = g_strdup ("G_MAXINT64");
+      else if (value == G_MAXUINT64)
+        desc = g_strdup ("G_MAXUINT64");
+      break;
+    default:
+      break;
+  }
+  if (!desc)
+    desc = g_strdup_printf ("%" G_GUINT64_FORMAT, value);
+
+  return desc;
+}
+
+static gchar*
+describe_type (GParamSpec *spec)
+{
+  gchar *desc;
+  gchar *lower;
+  gchar *upper;
+
+  if (G_IS_PARAM_SPEC_CHAR (spec)) {
+    GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
+
+    lower = describe_signed_constant (sizeof(gchar), pspec->minimum);
+    upper = describe_signed_constant (sizeof(gchar), pspec->maximum);
+    if (pspec->minimum == G_MININT8 && pspec->maximum == G_MAXINT8)
+      desc = g_strdup ("");
+    else if (pspec->minimum == G_MININT8)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXINT8)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_UCHAR (spec)) {
+    GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
+
+    lower = describe_unsigned_constant (sizeof(guchar), pspec->minimum);
+    upper = describe_unsigned_constant (sizeof(guchar), pspec->maximum);
+    if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT8)
+      desc = g_strdup ("");
+    else if (pspec->minimum == 0)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXUINT8)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_INT (spec)) {
+    GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
+
+    lower = describe_signed_constant (sizeof(gint), pspec->minimum);
+    upper = describe_signed_constant (sizeof(gint), pspec->maximum);
+    if (pspec->minimum == G_MININT && pspec->maximum == G_MAXINT)
+      desc = g_strdup ("");
+    else if (pspec->minimum == G_MININT)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXINT)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_UINT (spec)) {
+    GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
+
+    lower = describe_unsigned_constant (sizeof(guint), pspec->minimum);
+    upper = describe_unsigned_constant (sizeof(guint), pspec->maximum);
+    if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT)
+      desc = g_strdup ("");
+    else if (pspec->minimum == 0)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXUINT)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_LONG (spec)) {
+    GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
+
+    lower = describe_signed_constant (sizeof(glong), pspec->minimum);
+    upper = describe_signed_constant (sizeof(glong), pspec->maximum);
+    if (pspec->minimum == G_MINLONG && pspec->maximum == G_MAXLONG)
+      desc = g_strdup ("");
+    else if (pspec->minimum == G_MINLONG)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXLONG)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_ULONG (spec)) {
+    GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
+
+    lower = describe_unsigned_constant (sizeof(gulong), pspec->minimum);
+    upper = describe_unsigned_constant (sizeof(gulong), pspec->maximum);
+    if (pspec->minimum == 0 && pspec->maximum == G_MAXULONG)
+      desc = g_strdup ("");
+    else if (pspec->minimum == 0)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXULONG)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_INT64 (spec)) {
+    GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
+
+    lower = describe_signed_constant (sizeof(gint64), pspec->minimum);
+    upper = describe_signed_constant (sizeof(gint64), pspec->maximum);
+    if (pspec->minimum == G_MININT64 && pspec->maximum == G_MAXINT64)
+      desc = g_strdup ("");
+    else if (pspec->minimum == G_MININT64)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXINT64)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_UINT64 (spec)) {
+    GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
+
+    lower = describe_unsigned_constant (sizeof(guint64), pspec->minimum);
+    upper = describe_unsigned_constant (sizeof(guint64), pspec->maximum);
+    if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT64)
+      desc = g_strdup ("");
+    else if (pspec->minimum == 0)
+      desc = g_strdup_printf ("<= %s", upper);
+    else if (pspec->maximum == G_MAXUINT64)
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_FLOAT (spec)) {
+    GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
+
+    lower = describe_double_constant (pspec->minimum);
+    upper = describe_double_constant (pspec->maximum);
+    if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXFLOAT)) {
+      if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
+        desc = g_strdup ("");
+      else
+        desc = g_strdup_printf ("<= %s", upper);
+    }
+    else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+  else if (G_IS_PARAM_SPEC_DOUBLE (spec)) {
+    GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
+
+    lower = describe_double_constant (pspec->minimum);
+    upper = describe_double_constant (pspec->maximum);
+    if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXDOUBLE)) {
+      if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
+        desc = g_strdup ("");
+      else
+        desc = g_strdup_printf ("<= %s", upper);
+    }
+    else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
+      desc = g_strdup_printf (">= %s", lower);
+    else
+      desc = g_strdup_printf ("[%s,%s]", lower, upper);
+    g_free (lower);
+    g_free (upper);
+  }
+#if GLIB_CHECK_VERSION (2, 12, 0)
+  else if (G_IS_PARAM_SPEC_GTYPE (spec)) {
+    GParamSpecGType *pspec = G_PARAM_SPEC_GTYPE (spec);
+    gboolean is_pointer;
+
+    desc = g_strdup (get_type_name (pspec->is_a_type, &is_pointer));
+  }
+#endif
+#if GLIB_CHECK_VERSION (2, 25, 9)
+  else if (G_IS_PARAM_SPEC_VARIANT (spec)) {
+    GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
+    gchar *variant_type;
+
+    variant_type = g_variant_type_dup_string (pspec->type);
+    desc = g_strdup_printf ("GVariant<%s>", variant_type);
+    g_free (variant_type);
+  }
+#endif
+  else {
+    desc = g_strdup ("");
+  }
+
+  return desc;
+}
+
+static gchar*
+describe_default (GParamSpec *spec)
+{
+  gchar *desc;
+
+  if (G_IS_PARAM_SPEC_CHAR (spec)) {
+    GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
+
+    desc = g_strdup_printf ("%d", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_UCHAR (spec)) {
+    GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
+
+    desc = g_strdup_printf ("%u", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_BOOLEAN (spec)) {
+    GParamSpecBoolean *pspec = G_PARAM_SPEC_BOOLEAN (spec);
+
+    desc = g_strdup_printf ("%s", pspec->default_value ? "TRUE" : "FALSE");
+  }
+  else if (G_IS_PARAM_SPEC_INT (spec)) {
+    GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
+
+    desc = g_strdup_printf ("%d", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_UINT (spec)) {
+    GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
+
+    desc = g_strdup_printf ("%u", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_LONG (spec)) {
+    GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
+
+    desc = g_strdup_printf ("%ld", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_LONG (spec)) {
+    GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
+
+    desc = g_strdup_printf ("%lu", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_INT64 (spec)) {
+    GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
+
+    desc = g_strdup_printf ("%" G_GINT64_FORMAT, pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_UINT64 (spec))
+    {
+      GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
+
+      desc = g_strdup_printf ("%" G_GUINT64_FORMAT, pspec->default_value);
+    }
+  else if (G_IS_PARAM_SPEC_UNICHAR (spec)) {
+    GParamSpecUnichar *pspec = G_PARAM_SPEC_UNICHAR (spec);
+
+    if (g_unichar_isprint (pspec->default_value))
+      desc = g_strdup_printf ("'%c'", pspec->default_value);
+    else
+      desc = g_strdup_printf ("%u", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_ENUM (spec)) {
+    GParamSpecEnum *pspec = G_PARAM_SPEC_ENUM (spec);
+
+    GEnumValue *value = g_enum_get_value (pspec->enum_class, pspec->default_value);
+    if (value)
+      desc = g_strdup_printf ("%s", value->value_name);
+    else
+      desc = g_strdup_printf ("%d", pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_FLAGS (spec)) {
+    GParamSpecFlags *pspec = G_PARAM_SPEC_FLAGS (spec);
+    guint default_value;
+    GString *acc;
+
+    default_value = pspec->default_value;
+    acc = g_string_new ("");
+
+    while (default_value) {
+      GFlagsValue *value = g_flags_get_first_value (pspec->flags_class, default_value);
+
+      if (!value)
+        break;
+
+      if (acc->len > 0)
+        g_string_append (acc, " | ");
+      g_string_append (acc, value->value_name);
+
+      default_value &= ~value->value;
+    }
+
+    if (default_value == 0)
+      desc = g_string_free (acc, FALSE);
+    else {
+      desc = g_strdup_printf ("%d", pspec->default_value);
+      g_string_free (acc, TRUE);
+    }
+  }
+  else if (G_IS_PARAM_SPEC_FLOAT (spec)) {
+    GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
+
+    /* make sure floats are output with a decimal dot irrespective of
+     * current locale. Use formatd since we want human-readable numbers
+     * and do not need the exact same bit representation when deserialising */
+    desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
+    g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
+        pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_DOUBLE (spec)) {
+    GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
+
+    /* make sure floats are output with a decimal dot irrespective of
+     * current locale. Use formatd since we want human-readable numbers
+     * and do not need the exact same bit representation when deserialising */
+    desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
+    g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
+        pspec->default_value);
+  }
+  else if (G_IS_PARAM_SPEC_STRING (spec)) {
+    GParamSpecString *pspec = G_PARAM_SPEC_STRING (spec);
+
+    if (pspec->default_value) {
+      gchar *esc = g_strescape (pspec->default_value, NULL);
+      desc = g_strdup_printf ("\\"%s\\"", esc);
+      g_free (esc);
+    }
+    else
+      desc = g_strdup_printf ("NULL");
+  }
+#if GLIB_CHECK_VERSION (2, 25, 9)
+  else if (G_IS_PARAM_SPEC_VARIANT (spec)) {
+    GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
+
+    if (pspec->default_value)
+      desc = g_variant_print (pspec->default_value, TRUE);
+    else
+      desc = g_strdup ("NULL");
+  }
+#endif
+  else {
+    desc = g_strdup ("");
+  }
+
+  return desc;
+}
+
+
+static void
+output_object_args (FILE *fp, GType object_type)
+{
+  gpointer class;
+  const gchar *object_class_name;
+  guint arg;
+  gchar flags[16], *pos;
+  GParamSpec **properties;
+  guint n_properties;
+  gboolean child_prop;
+  gboolean style_prop;
+  gboolean is_pointer;
+  const gchar *type_name;
+  gchar *type_desc;
+  gchar *default_value;
+
+  if (G_TYPE_IS_OBJECT (object_type)) {
+    class = g_type_class_peek (object_type);
+    if (!class)
+      return;
+
+    properties = g_object_class_list_properties (class, &n_properties);
+  }
+#if GLIB_MAJOR_VERSION > 2 || (GLIB_MAJOR_VERSION == 2 && GLIB_MINOR_VERSION >= 3)
+  else if (G_TYPE_IS_INTERFACE (object_type)) {
+    class = g_type_default_interface_ref (object_type);
+
+    if (!class)
+      return;
+
+    properties = g_object_interface_list_properties (class, &n_properties);
+  }
+#endif
+  else
+    return;
+
+  object_class_name = g_type_name (object_type);
+
+  child_prop = FALSE;
+  style_prop = FALSE;
+
+  while (TRUE) {
+    qsort (properties, n_properties, sizeof (GParamSpec *), compare_param_specs);
+    for (arg = 0; arg < n_properties; arg++) {
+      GParamSpec *spec = properties[arg];
+      const gchar *nick, *blurb, *dot;
+
+      if (spec->owner_type != object_type)
+        continue;
+
+      pos = flags;
+      /* We use one-character flags for simplicity. */
+      if (child_prop && !style_prop)
+           *pos++ = 'c';
+      if (style_prop)
+           *pos++ = 's';
+      if (spec->flags & G_PARAM_READABLE)
+         *pos++ = 'r';
+      if (spec->flags & G_PARAM_WRITABLE)
+        *pos++ = 'w';
+      if (spec->flags & G_PARAM_CONSTRUCT)
+        *pos++ = 'x';
+      if (spec->flags & G_PARAM_CONSTRUCT_ONLY)
+        *pos++ = 'X';
+      *pos = 0;
+
+      nick = g_param_spec_get_nick (spec);
+      blurb = g_param_spec_get_blurb (spec);
+
+      dot = "";
+      if (blurb) {
+        int str_len = strlen (blurb);
+        if (str_len > 0  && blurb[str_len - 1] != '.')
+          dot = ".";
+      }
+
+      type_desc = describe_type (spec);
+      default_value = describe_default (spec);
+      type_name = get_type_name (spec->value_type, &is_pointer);
+      fprintf (fp, "\\n"
+                   "%s::%s\\n"
+                   "%s%s\\n"
+                   "%s\\n"
+                   "%s\\n"
+                   "%s\\n"
+                   "%s%s\\n"
+                   "%s\\n"
+                   "\\n\\n",
+               object_class_name, g_param_spec_get_name (spec), type_name,
+               is_pointer ? "*" : "", type_desc, flags, nick ? nick : "(null)",
+               blurb ? blurb : "(null)", dot, default_value);
+      g_free (type_desc);
+      g_free (default_value);
+    }
+
+    g_free (properties);
+
+#ifdef GTK_IS_CONTAINER_CLASS
+#if !GTK_CHECK_VERSION(3,96,0)
+    if (!child_prop && GTK_IS_CONTAINER_CLASS (class)) {
+      properties = gtk_container_class_list_child_properties (class, &n_properties);
+      child_prop = TRUE;
+      continue;
+    }
+#endif
+#endif
+
+#ifdef GTK_IS_CELL_AREA_CLASS
+    if (!child_prop && GTK_IS_CELL_AREA_CLASS (class)) {
+      properties = gtk_cell_area_class_list_cell_properties (class, &n_properties);
+      child_prop = TRUE;
+      continue;
+    }
+#endif
+
+#ifdef GTK_IS_WIDGET_CLASS
+#if GTK_CHECK_VERSION(2,1,0) && !GTK_CHECK_VERSION(3,89,2)
+    if (!style_prop && GTK_IS_WIDGET_CLASS (class)) {
+      properties = gtk_widget_class_list_style_properties (GTK_WIDGET_CLASS (class), &n_properties);
+      style_prop = TRUE;
+      continue;
+    }
+#endif
+#endif
+
+"""
+
+MAIN_CODE_END = """
+    break;
+  }
+}
+"""
+
+
+def execute_command(options, description, command, env=None):
+    if options.verbose:
+        call = subprocess.check_call
+    else:
+        call = subprocess.check_output
+
+    try:
+        call(command, env=env)
+    except subprocess.CalledProcessError as e:
+        logging.warning('%s scanner failed: %d, command: %s', description,
+                        e.returncode, ' '.join(command))
+        return e.returncode
+    except OSError as e:
+        logging.warning('%s scanner failed: %s, command: %s', description,
+                        str(e), ' '.join(command))
+        return 1
+    return 0
+
+
+def run(options):
+    logging.info('options: %s', str(options.__dict__))
+
+    c_file = options.module + '-scan.c'
+    output = open(c_file, 'w', encoding='utf-8')
+
+    base_filename = os.path.join(options.output_dir, options.module)
+    old_signals_filename = base_filename + '.signals'
+    new_signals_filename = base_filename + '.signals.new'
+    old_hierarchy_filename = base_filename + '.hierarchy'
+    new_hierarchy_filename = base_filename + '.hierarchy.new'
+    old_interfaces_filename = base_filename + '.interfaces'
+    new_interfaces_filename = base_filename + '.interfaces.new'
+    old_prerequisites_filename = base_filename + '.prerequisites'
+    new_prerequisites_filename = base_filename + '.prerequisites.new'
+    old_args_filename = base_filename + '.args'
+    new_args_filename = base_filename + '.args.new'
+    old_actions_filename = base_filename + '.actions'
+    new_actions_filename = base_filename + '.actions.new'
+
+    # generate a C program to scan the types
+
+    includes = ""
+    forward_decls = ""
+    get_types = ""
+    ntypes = 1
+
+    for line in open(options.types, 'r', encoding='utf-8'):
+        if line.startswith('#include'):
+            includes += line
+        elif line.startswith('%') or line.strip() == '':
+            continue
+        else:
+            line = line.strip()
+            get_types += '  object_types[i++] = ' + line + ' ();\n'
+            forward_decls += 'extern GType ' + line + ' (void);\n'
+            ntypes += 1
+
+    output.write(COMMON_INCLUDES)
+
+    if includes:
+        output.write(includes)
+    else:
+        output.write(forward_decls)
+
+    if options.query_child_properties:
+        output.write(QUERY_CHILD_PROPS_PROTOTYPE % options.query_child_properties)
+
+    # substitute local vars in the template
+    type_init_func = options.type_init_func
+    main_func_params = "int argc, char *argv[]"
+    if "argc" in type_init_func and "argv" not in type_init_func:
+        main_func_params = "int argc, G_GNUC_UNUSED char *argv[]"
+    elif "argc" not in type_init_func and "argv" in type_init_func:
+        main_func_params = "G_GNUC_UNUSED int argc, char *argv[]"
+    elif "argc" not in type_init_func and "argv" not in type_init_func:
+        main_func_params = "void"
+
+    # TODO: we should explicitly reference the vars that we substitute
+    # template_vars = {
+    #     'get_types': get_types,
+    #     'ntypes': ntypes,
+    #     'main_func_params', main_func_params,
+    #     'new_args_filename': new_args_filename,
+    #     'new_hierarchy_filename': new_hierarchy_filename,
+    #     'new_interfaces_filename': new_interfaces_filename,
+    #     'new_prerequisites_filename': new_prerequisites_filename,
+    #     'new_signals_filename': new_signals_filename,
+    #     'type_init_func': type_init_func
+    # }
+    # output.write(string.Template(MAIN_CODE).substitute(template_vars))
+    output.write(string.Template(MAIN_CODE).substitute(locals()))
+
+    if options.query_child_properties:
+        output.write(QUERY_CHILD_PROPS_CODE % options.query_child_properties)
+
+    output.write(MAIN_CODE_END)
+
+    output.close()
+
+    # Compile and run our file
+    if 'libtool' in options.cc:
+        o_file = options.module + '-scan.lo'
+    else:
+        o_file = options.module + '-scan.o'
+
+    x_file = options.module + '-scan' + config.exeext
+
+    logging.debug('Intermediate scanner files: %s, %s, %s', c_file, o_file, x_file)
+
+    res = execute_command(options, 'Compiling',
+                          shlex.split(options.cc) + shlex.split(options.cflags) +
+                          ["-c", "-o", o_file, c_file])
+    if res:
+        return res
+
+    res = execute_command(options, 'Linking',
+                          shlex.split(options.ld) + [o_file] +
+                          shlex.split(options.ldflags) + ['-o', x_file])
+    if res:
+        return res
+
+    run_env = os.environ.copy()
+    run_env['LC_MESSAGES'] = 'C'
+    run_env.pop('LC_ALL', None)
+    res = execute_command(options, 'Running',
+                          shlex.split(options.run) + ['./' + x_file],
+                          env=run_env)
+    if res:
+        return res
+
+    logging.debug('Scan complete')
+    if 'GTK_DOC_KEEP_INTERMEDIATE' not in os.environ:
+        os.unlink(c_file)
+        os.unlink(o_file)
+        os.unlink(x_file)
+        if 'libtool' in options.cc:
+            o_file = options.module + '-scan.o'
+            if os.path.exists(o_file):
+                os.unlink(o_file)
+    else:
+        logging.debug('Keeping generated sources for analysis: %s, %s, %s',
+                      c_file, o_file, x_file)
+
+    common.UpdateFileIfChanged(old_signals_filename, new_signals_filename, False)
+    common.UpdateFileIfChanged(old_hierarchy_filename, new_hierarchy_filename, False)
+    common.UpdateFileIfChanged(old_interfaces_filename, new_interfaces_filename, False)
+    common.UpdateFileIfChanged(old_prerequisites_filename, new_prerequisites_filename, False)
+    common.UpdateFileIfChanged(old_args_filename, new_args_filename, False)
+    common.UpdateFileIfChanged(old_actions_filename, new_actions_filename, False)
+
+    return 0
diff --git a/gtk-doc-for-gtk4/gtkdoc_uninstalled.py.in b/gtk-doc-for-gtk4/gtkdoc_uninstalled.py.in
new file mode 100644
index 0000000000..8febefd75e
--- /dev/null
+++ b/gtk-doc-for-gtk4/gtkdoc_uninstalled.py.in
@@ -0,0 +1,5 @@
+import sys
+
+sourcedir = "@sourcedir@"
+builddir = "@builddir@"
+sys.path.append(sourcedir)
diff --git a/gtk-doc-for-gtk4/help/Makefile.am b/gtk-doc-for-gtk4/help/Makefile.am
new file mode 100644
index 0000000000..6690244c3f
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/Makefile.am
@@ -0,0 +1,7 @@
+## Process this file with automake to produce Makefile.in
+
+if HAVE_YELP_TOOLS
+SUBDIRS = manual
+endif
+
+-include $(top_srcdir)/git.mk
diff --git a/gtk-doc-for-gtk4/help/manual/C/fdl-appendix.xml b/gtk-doc-for-gtk4/help/manual/C/fdl-appendix.xml
new file mode 100644
index 0000000000..d36c0bc39f
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/manual/C/fdl-appendix.xml
@@ -0,0 +1,671 @@
+
+
+
+  
+    
+      Version 1.1, March 2000
+    
+    
+      2000Free Software Foundation, Inc.
+    
+    
+      
+	
    Free Software Foundation, Inc. 51 Franklin Street, 
+        Suite 330, Boston, MA  
+        02110-1301  USA
     
+	Everyone is permitted to copy and distribute verbatim copies of this 
+        license document, but changing it is not allowed.
+          
+        
+      
+  GNU Free Documentation License
+
+  
+    0. PREAMBLE
+    
+      The purpose of this License is to make a manual, textbook, or
+      other written document free in the sense of
+      freedom: to assure everyone the effective freedom to copy and
+      redistribute it, with or without modifying it, either
+      commercially or noncommercially. Secondarily, this License
+      preserves for the author and publisher a way to get credit for
+      their work, while not being considered responsible for
+      modifications made by others.
+    
+    
+    
+      This License is a kind of copyleft, which means
+      that derivative works of the document must themselves be free in
+      the same sense. It complements the GNU General Public License,
+      which is a copyleft license designed for free software.
+    
+    
+    
+      We have designed this License in order to use it for manuals for
+      free software, because free software needs free documentation: a
+      free program should come with manuals providing the same
+      freedoms that the software does. But this License is not limited
+      to software manuals; it can be used for any textual work,
+      regardless of subject matter or whether it is published as a
+      printed book. We recommend this License principally for works
+      whose purpose is instruction or reference.
+    
+  
+  
+    1. APPLICABILITY AND DEFINITIONS
+    
+      This License applies to any manual or other work that contains a
+      notice placed by the copyright holder saying it can be
+      distributed under the terms of this License. The
+      Document, below, refers to any such manual or
+      work. Any member of the public is a licensee, and is addressed
+      as you.
+    
+    
+    
+      A Modified Version of the Document means any work
+      containing the Document or a portion of it, either copied
+      verbatim, or with modifications and/or translated into another
+      language.
+    
+	
+    
+      A Secondary Section is a named appendix or a
+      front-matter section of the Document that deals exclusively
+      with the relationship of the publishers or authors of the
+      Document to the Document's overall subject (or to related
+      matters) and contains nothing that could fall directly within
+      that overall subject. (For example, if the Document is in part a
+      textbook of mathematics, a Secondary Section may not explain any
+      mathematics.)  The relationship could be a matter of historical
+      connection with the subject or with related matters, or of
+      legal, commercial, philosophical, ethical or political position
+      regarding them.
+    
+
+    
+      The Invariant Sections are certain  Secondary Sections whose titles
+      are designated, as being those of Invariant Sections, in the
+      notice that says that the Document is released under this
+      License.
+    
+    
+    
+      The Cover Texts are certain short passages of
+      text that are listed, as Front-Cover Texts or Back-Cover Texts,
+      in the notice that says that the Document is released under this
+      License.
+    
+	
+    
+      A Transparent copy of the  Document means a machine-readable
+      copy, represented in a format whose specification is available
+      to the general public, whose contents can be viewed and edited
+      directly and straightforwardly with generic text editors or (for
+      images composed of pixels) generic paint programs or (for
+      drawings) some widely available drawing editor, and that is
+      suitable for input to text formatters or for automatic
+      translation to a variety of formats suitable for input to text
+      formatters. A copy made in an otherwise Transparent file format
+      whose markup has been designed to thwart or discourage
+      subsequent modification by readers is not Transparent.  A copy
+      that is not Transparent is called
+      Opaque.
+    
+    
+    
+      Examples of suitable formats for Transparent copies include
+      plain ASCII without markup, Texinfo input format, LaTeX input
+      format, SGML or XML using a publicly available DTD, and
+      standard-conforming simple HTML designed for human
+      modification. Opaque formats include PostScript, PDF,
+      proprietary formats that can be read and edited only by
+      proprietary word processors, SGML or XML for which the DTD
+      and/or processing tools are not generally available, and the
+      machine-generated HTML produced by some word processors for
+      output purposes only.
+    
+    
+    
+      The Title Page means, for a printed book, the
+      title page itself, plus such following pages as are needed to
+      hold, legibly, the material this License requires to appear in
+      the title page. For works in formats which do not have any title
+      page as such, Title Page means the text near the
+      most prominent appearance of the work's title, preceding the
+      beginning of the body of the text.
+    
+  
+    
+  
+    2. VERBATIM COPYING
+    
+      You may copy and distribute the Document in any medium, either
+      commercially or noncommercially, provided that this License, the
+      copyright notices, and the license notice saying this License
+      applies to the Document are reproduced in all copies, and that
+      you add no other conditions whatsoever to those of this
+      License. You may not use technical measures to obstruct or
+      control the reading or further copying of the copies you make or
+      distribute. However, you may accept compensation in exchange for
+      copies. If you distribute a large enough number of copies you
+      must also follow the conditions in section 3.
+    
+    
+    
+      You may also lend copies, under the same conditions stated
+      above, and you may publicly display copies.
+    
+    
+    
+  
+    3. COPYING IN QUANTITY
+    
+      If you publish printed copies of the Document numbering more than 100,
+      and the Document's license notice requires Cover Texts, you must enclose
+      the copies in covers that carry, clearly and legibly, all these
+      Cover Texts: Front-Cover Texts on the front cover, and
+      Back-Cover Texts on the back cover. Both covers must also
+      clearly and legibly identify you as the publisher of these
+      copies. The front cover must present the full title with all
+      words of the title equally prominent and visible. You may add
+      other material on the covers in addition. Copying with changes
+      limited to the covers, as long as they preserve the title of the
+      Document and satisfy these
+      conditions, can be treated as verbatim copying in other
+      respects.
+    
+    
+    
+      If the required texts for either cover are too voluminous to fit
+      legibly, you should put the first ones listed (as many as fit
+      reasonably) on the actual cover, and continue the rest onto
+      adjacent pages.
+    
+    
+    
+      If you publish or distribute Opaque copies of the Document numbering more than 100,
+      you must either include a machine-readable Transparent copy along with
+      each Opaque copy, or state in or with each Opaque copy a
+      publicly-accessible computer-network location containing a
+      complete Transparent copy of the Document, free of added
+      material, which the general network-using public has access to
+      download anonymously at no charge using public-standard network
+      protocols. If you use the latter option, you must take
+      reasonably prudent steps, when you begin distribution of Opaque
+      copies in quantity, to ensure that this Transparent copy will
+      remain thus accessible at the stated location until at least one
+      year after the last time you distribute an Opaque copy (directly
+      or through your agents or retailers) of that edition to the
+      public.
+    
+    
+    
+      It is requested, but not required, that you contact the authors
+      of the Document well before
+      redistributing any large number of copies, to give them a chance
+      to provide you with an updated version of the Document.
+    
+    
+    
+  
+    4. MODIFICATIONS
+    
+      You may copy and distribute a Modified Version of the Document under the conditions of
+      sections 2 and 3 above, provided that you release
+      the Modified Version under precisely this License, with the
+      Modified Version filling the role of the Document, thus
+      licensing distribution and modification of the Modified Version
+      to whoever possesses a copy of it. In addition, you must do
+      these things in the Modified Version:
+    
+    
+    
+      
+	
+	  A
+	  
+	    Use in the Title
+	    Page (and on the covers, if any) a title distinct
+	    from that of the Document, and from those of
+	    previous versions (which should, if there were any, be
+	    listed in the History section of the Document). You may
+	    use the same title as a previous version if the original
+	    publisher of that version gives permission.
+	  
+	
+      
+      
+      
+	
+	  B
+	  
+	    List on the Title
+	    Page, as authors, one or more persons or entities
+	    responsible for authorship of the modifications in the
+	    Modified Version,
+	    together with at least five of the principal authors of
+	    the Document (all of
+	    its principal authors, if it has less than five).
+	  
+	
+      
+      
+      
+	
+	  C
+	  
+	    State on the Title
+	    Page the name of the publisher of the Modified Version, as the
+	    publisher.
+	  
+	
+      
+      
+      
+	
+	  D
+	  
+	    Preserve all the copyright notices of the Document.
+	  
+	
+      
+      
+      
+	
+	  E
+	  
+	    Add an appropriate copyright notice for your modifications
+	    adjacent to the other copyright notices.
+	  
+	
+      
+      
+      
+	
+	  F
+	  
+	    Include, immediately after the copyright notices, a
+	    license notice giving the public permission to use the
+	    Modified Version under
+	    the terms of this License, in the form shown in the
+	    Addendum below.
+	  
+	
+      
+      
+      
+	
+	  G
+	  
+	    Preserve in that license notice the full lists of  Invariant Sections and
+	    required Cover
+	    Texts given in the Document's license notice.
+	  
+	
+      
+      
+      
+	
+	  H
+	  
+	    Include an unaltered copy of this License.
+	  
+	
+      
+      
+      
+	
+	  I
+	  
+	    Preserve the section entitled History, and
+	    its title, and add to it an item stating at least the
+	    title, year, new authors, and publisher of the Modified Version as given on
+	    the Title Page.  If
+	    there is no section entitled History in the
+	    Document, create one
+	    stating the title, year, authors, and publisher of the
+	    Document as given on its Title Page, then add an item
+	    describing the Modified Version as stated in the previous
+	    sentence.
+	  
+	
+      
+      
+      
+	
+	  J
+	  
+	    Preserve the network location, if any, given in the Document for public access
+	    to a Transparent
+	    copy of the Document, and likewise the network locations
+	    given in the Document for previous versions it was based
+	    on. These may be placed in the History
+	    section.  You may omit a network location for a work that
+	    was published at least four years before the Document
+	    itself, or if the original publisher of the version it
+	    refers to gives permission.
+	  
+	
+      
+      
+      
+	
+	  K
+	  
+	    In any section entitled Acknowledgements or
+	    Dedications, preserve the section's title,
+	    and preserve in the section all the substance and tone of
+	    each of the contributor acknowledgements and/or
+	    dedications given therein.
+	  
+	
+      
+      
+      
+	
+	  L
+	  
+	    Preserve all the Invariant
+	    Sections of the Document, unaltered in their
+	    text and in their titles.  Section numbers or the
+	    equivalent are not considered part of the section titles.
+	  
+	
+      
+      
+      
+	
+	  M
+	  
+	    Delete any section entitled
+	    Endorsements. Such a section may not be
+	    included in the Modified
+	    Version.
+	  
+	
+      
+      
+      
+	
+	  N
+	  
+	    Do not retitle any existing section as
+	    Endorsements or to conflict in title with
+	    any Invariant
+	    Section.
+	  
+	
+      
+    
+    
+    
+      If the Modified Version
+      includes new front-matter sections or appendices that qualify as
+      Secondary Sections and
+      contain no material copied from the Document, you may at your
+      option designate some or all of these sections as invariant. To
+      do this, add their titles to the list of Invariant Sections in the
+      Modified Version's license notice.  These titles must be
+      distinct from any other section titles.
+    
+    
+    
+      You may add a section entitled Endorsements,
+      provided it contains nothing but endorsements of your Modified Version by various
+      parties--for example, statements of peer review or that the text
+      has been approved by an organization as the authoritative
+      definition of a standard.
+    
+    
+    
+      You may add a passage of up to five words as a Front-Cover Text, and a passage
+      of up to 25 words as a Back-Cover Text, to the end of
+      the list of Cover Texts
+      in the Modified Version.
+      Only one passage of Front-Cover Text and one of Back-Cover Text
+      may be added by (or through arrangements made by) any one
+      entity. If the Document
+      already includes a cover text for the same cover, previously
+      added by you or by arrangement made by the same entity you are
+      acting on behalf of, you may not add another; but you may
+      replace the old one, on explicit permission from the previous
+      publisher that added the old one.
+    
+    
+    
+      The author(s) and publisher(s) of the Document do not by this License
+      give permission to use their names for publicity for or to
+      assert or imply endorsement of any Modified Version .
+    
+  
+    
+  
+    5. COMBINING DOCUMENTS
+    
+      You may combine the Document
+      with other documents released under this License, under the
+      terms defined in section 4
+      above for modified versions, provided that you include in the
+      combination all of the Invariant
+      Sections of all of the original documents, unmodified,
+      and list them all as Invariant Sections of your combined work in
+      its license notice.
+    
+    
+    
+      The combined work need only contain one copy of this License,
+      and multiple identical Invariant
+      Sections may be replaced with a single copy. If there are
+      multiple Invariant Sections with the same name but different
+      contents, make the title of each such section unique by adding
+      at the end of it, in parentheses, the name of the original
+      author or publisher of that section if known, or else a unique
+      number. Make the same adjustment to the section titles in the
+      list of Invariant Sections in the license notice of the combined
+      work.
+    
+    
+    
+      In the combination, you must combine any sections entitled
+      History in the various original documents,
+      forming one section entitled History; likewise
+      combine any sections entitled Acknowledgements,
+      and any sections entitled Dedications.  You must
+      delete all sections entitled Endorsements.
+    
+    
+    
+  
+    6. COLLECTIONS OF DOCUMENTS
+    
+      You may make a collection consisting of the Document and other documents
+      released under this License, and replace the individual copies
+      of this License in the various documents with a single copy that
+      is included in the collection, provided that you follow the
+      rules of this License for verbatim copying of each of the
+      documents in all other respects.
+    
+    
+    
+      You may extract a single document from such a collection, and
+      distribute it individually under this License, provided you
+      insert a copy of this License into the extracted document, and
+      follow this License in all other respects regarding verbatim
+      copying of that document.
+    
+    
+    
+  
+    7. AGGREGATION WITH INDEPENDENT WORKS
+    
+      A compilation of the Document or its derivatives with
+      other separate and independent documents or works, in or on a
+      volume of a storage or distribution medium, does not as a whole
+      count as a Modified Version
+      of the Document, provided no compilation copyright is claimed
+      for the compilation.  Such a compilation is called an
+      aggregate, and this License does not apply to the
+      other self-contained works thus compiled with the Document , on
+      account of their being thus compiled, if they are not themselves
+      derivative works of the Document.  If the Cover Text requirement of section 3 is applicable to these
+      copies of the Document, then if the Document is less than one
+      quarter of the entire aggregate, the Document's Cover Texts may
+      be placed on covers that surround only the Document within the
+      aggregate. Otherwise they must appear on covers around the whole
+      aggregate.
+    
+    
+    
+  
+    8. TRANSLATION
+    
+      Translation is considered a kind of modification, so you may
+      distribute translations of the Document under the terms of section 4. Replacing  Invariant Sections with
+      translations requires special permission from their copyright
+      holders, but you may include translations of some or all
+      Invariant Sections in addition to the original versions of these
+      Invariant Sections. You may include a translation of this
+      License provided that you also include the original English
+      version of this License. In case of a disagreement between the
+      translation and the original English version of this License,
+      the original English version will prevail.
+    
+    
+    
+  
+    9. TERMINATION
+    
+      You may not copy, modify, sublicense, or distribute the Document except as expressly
+      provided for under this License. Any other attempt to copy,
+      modify, sublicense or distribute the Document is void, and will
+      automatically terminate your rights under this License. However,
+      parties who have received copies, or rights, from you under this
+      License will not have their licenses terminated so long as such
+      parties remain in full compliance.
+    
+    
+    
+  
+    10. FUTURE REVISIONS OF THIS LICENSE
+    
+      The Free Software
+      Foundation may publish new, revised versions of the GNU
+      Free Documentation License from time to time. Such new versions
+      will be similar in spirit to the present version, but may differ
+      in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
+    
+    
+    
+      Each version of the License is given a distinguishing version
+      number. If the Document
+      specifies that a particular numbered version of this License
+      or any later version applies to it, you have the
+      option of following the terms and conditions either of that
+      specified version or of any later version that has been
+      published (not as a draft) by the Free Software Foundation. If
+      the Document does not specify a version number of this License,
+      you may choose any version ever published (not as a draft) by
+      the Free Software Foundation.
+    
+  
+
+  
+    Addendum
+    
+      To use this License in a document you have written, include a copy of
+      the License in the document and put the following copyright and
+      license notices just after the title page:
+    
+    
+    
    
+      
+	Copyright YEAR YOUR NAME.
+      
+      
+	Permission is granted to copy, distribute and/or modify this
+	document under the terms of the GNU Free Documentation
+	License, Version 1.1 or any later version published by the
+	Free Software Foundation; with the Invariant Sections being LIST
+	THEIR TITLES, with the Front-Cover Texts being LIST,
+	and with the Back-Cover
+	Texts being LIST.  A copy of the license is included in
+	the section entitled GNU Free Documentation
+	License.
+      
+    
    
+      
+    
+      If you have no Invariant
+      Sections, write with no Invariant Sections
+      instead of saying which ones are invariant.  If you have no
+      Front-Cover Texts, write
+      no Front-Cover Texts instead of
+      Front-Cover Texts being LIST; likewise for Back-Cover Texts.
+    
+    
+    
+      If your document contains nontrivial examples of program code,
+      we recommend releasing these examples in parallel under your
+      choice of free software license, such as the  GNU General Public
+      License, to permit their use in free software.
+    
+      
+      
+
+
+
+
+
+
diff --git a/gtk-doc-for-gtk4/help/manual/C/index.docbook b/gtk-doc-for-gtk4/help/manual/C/index.docbook
new file mode 100644
index 0000000000..36b51fecce
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/manual/C/index.docbook
@@ -0,0 +1,2601 @@
+
+
+
+
+included">
+]>
+
+  
+    GTK-Doc Manual
+    1.24.1
+    User manual for developers with instructions of GTK-Doc usage.
+    
+      
+        Chris
+        Lyttle
+        
+          
    
+            chris@wilddev.net
+          
    
+            
+          
+      
+        Dan
+        Mueth
+        
+          
    
+            d-mueth@uchicago.edu
+          
    
+            
+          
+      
+        Stefan
+        Sauer (Kost)
+        
+          
    
+            ensonic@users.sf.net
+          
    
+            
+          
+        
+    
+      GTK-Doc project
+      
    gtk-doc-list@gnome.org
    
+        
+    
+      2000, 2005
+      Dan Mueth and Chris Lyttle
+    
+    
+      2007-2019
+      Stefan Sauer (Kost)
+    
+
+    
+
+    
+      
+        Permission is granted to copy, distribute and/or modify this
+        document under the terms of the GNU Free Documentation
+        License, Version 1.1 or any later version published
+        by the Free Software Foundation with no Invariant Sections, no
+        Front-Cover Texts, and no Back-Cover Texts. A copy of the license
+        is &FDLlink;.
+      
+      
+        Many of the names used by companies to distinguish their products and
+        services are claimed as trademarks. Where those names appear in any
+        GNOME documentation, and those trademarks are made aware to the members
+        of the GNOME Documentation Project, the names have been printed in caps
+        or initial caps.
+      
+    
+
+    
+      
+         1.32.1
+         15 Aug 2019
+         ss
+         dev version
+      
+      
+         1.32
+         15 Aug 2019
+         ss
+         hotfix release
+      
+      
+         1.31
+         05 Aug 2019
+         ss
+         refactorings and more test coverage
+      
+      
+         1.30
+         08 May 2019
+         ss
+         more test coverage
+      
+      
+         1.29
+         28 Aug 2018
+         ss
+         bug fixes
+      
+      
+         1.28
+         24 Mar 2018
+         ss
+         bug fixes
+      
+      
+         1.27
+         07 Dec 2017
+         ss
+         fine tuning of the python port
+      
+      
+         1.26
+         11 Aug 2017
+         ss
+         port all tools from perl/bash to python
+      
+      
+        1.25
+        21 March 2016
+        ss
+        bug fixes, test cleanups
+      
+      
+        1.24
+        29 May 2015
+        ss
+        bug fix
+      
+      
+        1.23
+        17 May 2015
+        ss
+        bug fix
+      
+      
+        1.22
+        07 May 2015
+        ss
+        bug fixes, dropping deprecated features
+      
+      
+        1.21
+        17 Jul 2014
+        ss
+        bug fixes, dropping deprecated features
+      
+      
+        1.20
+        16 Feb 2014
+        ss
+        bug fixes, markdown support, style improvements
+      
+      
+        1.19
+        05 Jun 2013
+        ss
+        bug fixes
+      
+      
+        1.18
+        14 Sep 2011
+        ss
+        bug fixes, speedups, markdown support
+      
+      
+        1.17
+        26 Feb 2011
+        sk
+        urgent bug fix update
+      
+      
+        1.16
+        14 Jan 2011
+        sk
+        bugfixes, layout improvements
+      
+      
+        1.15
+        21 May 2010
+        sk
+        bug and regression fixes
+      
+      
+        1.14
+        28 March 2010
+        sk
+        bugfixes and performance improvements
+      
+      
+        1.13
+        18 December 2009
+        sk
+        broken tarball update
+      
+      
+        1.12
+        18 December 2009
+        sk
+        new tool features and bugfixes
+      
+      
+        1.11
+        16 November 2008
+        mal
+        GNOME doc-utils migration
+      
+    
+
+      
+
+  
+
+  
+    Introduction
+
+    
+      This chapter introduces GTK-Doc and gives an overview of what it is and
+      how it is used.
+    
+
+    
+      What is GTK-Doc?
+
+      
+        GTK-Doc is used to document C code. It is typically used to document the public
+        API of libraries, such as the GTK+ and GNOME libraries. But it can also be
+        used to document application code.
+      
+    
+
+    
+      How Does GTK-Doc Work?
+
+      
+        GTK-Doc works by using documentation of functions placed inside the source files in
+        specially-formatted comment blocks, or documentation added to the template files
+        which GTK-Doc uses (though note that GTK-Doc will only document functions that
+        are declared in header files; it won't produce output for static functions).
+      
+
+      
+        GTK-Doc consists of a number of python scripts, each performing a different step
+        in the process.
+      
+
+      
+        There are 5 main steps in the process:
+      
+
+      
+
+        
+          
+            Writing the documentation.
+
+            The author fills in the source files with the documentation for each
+            function, macro, structs or unions, etc.
+          
+        
+
+        
+          
+            Gathering information about the code.
+
+            gtkdoc-scan scans the header files of the
+            code looking for declarations of functions, macros, enums, structs, and unions.
+            It creates the file <module>-decl-list.txt containing a list of the
+            declarations, placing them into sections according to which header file they
+            are in. On the first run this file is copied to <module>-sections.txt.
+            The author can rearrange the sections, and the order of the
+            declarations within them, to produce the final desired order.
+            The second file it generates is <module>-decl.txt.
+            This file contains the full declarations found by the scanner. If for
+            some reason one would like some symbols to show up in the docs, where
+            the full declaration cannot be found by the scanner or the declaration
+            should appear differently, one can place entities similar to the ones in
+            <module>-decl.txt into <module>-overrides.txt.
+         
+         
+            gtkdoc-scangobj can also be used to dynamically query a library about
+            any GObject subclasses it exports. It saves information about each
+            object's position in the class hierarchy and about any GObject properties
+            and signals it provides.
+          
+         
+            gtkdoc-scanobj should not be used anymore.
+            It was needed in the past when GObject was still GtkObject inside gtk+.
+         
+        
+
+        
+          
+            Generating the XML and HTML/PDF.
+
+            gtkdoc-mkdb turns the template files into
+            XML files in the xml/ subdirectory.
+            If the source code contains documentation on functions, using the
+            special comment blocks, it gets merged in here. If there are no tmpl files used
+            it only reads docs from sources and introspection data.
+          
+          
+            gtkdoc-mkhtml turns the XML files into HTML
+            files in the html/ subdirectory.
+            Likewise gtkdoc-mkpdf turns the XML files into a PDF
+            document called <package>.pdf.
+          
+          
+            Files in xml/ and
+            html/ directories are always
+            overwritten. One should never edit them directly.
+          
+        
+
+        
+          
+            Fixing up cross-references between documents.
+
+            After installing the HTML files, gtkdoc-fixxref can be run to fix up any
+            cross-references between separate documents. For example, the GTK+
+            documentation contains many cross-references to types documented in the GLib manual.
+
+            When creating the source tarball for distribution, gtkdoc-rebase
+            turns all external links into web-links. When installing distributed (pregenerated) docs
+            the same application will try to turn links back to local links
+            (where those docs are installed).
+          
+        
+      
+
+    
+
+    
+      Getting GTK-Doc
+
+      
+        Requirements
+        
+          python 2/3 - the main scripts are written in python.
+        
+        
+          xsltproc - the xslt processor from libxslt
+          xmlsoft.org/XSLT/
+        
+        
+          docbook-xsl - the docbook xsl stylesheets
+          sourceforge.net/projects/docbook/files/docbook-xsl
+        
+        
+          One of source-highlight, highlight or
+          vim - optional - used for syntax highlighting of examples
+        
+      
+    
+
+    
+      About GTK-Doc
+
+      
+        Historically GTK-Doc was used to generate template files from the sources
+        code. These template files could be used by developers to enter the
+        API documentation. This approach was rather inconvenient because it
+        required to keep the generated files under version control.
+        Since GTK-Doc 1.9 it became possible to place all API information
+        into source comments, which made the template support obsolete.
+        In version 1.26 template support has been removed.
+      
+
+      
+        (FIXME)
+      
+
+      
+        (authors, web pages, mailing list, license, future plans,
+        comparison with other similar systems.)
+      
+
+    
+
+    
+      About this Manual
+
+      
+        (FIXME)
+      
+
+      
+        (who it is meant for, where you can get it, license)
+      
+
+    
+
+  
+
+  
+    Project Setup
+
+    
+      This Chapter describes the steps that are necessary to integrate GTK-Doc
+      into your project. The integration of GTK-Doc into a project includes the
+      following steps:
+    
+
+    
+      
+        
+          Preparation of the directory structure and creating required
+          configuration files for your GTK-Doc documentation (see
+          
+            Setting up a skeleton documentation).
+        
+      
+      
+        
+          Adjusting the build system to build your documentation using the
+          GTK-Doc tools. Multiple build systems are supported, in
+          this manual we describe how to integrate GTK-Doc with
+          Autotools,
+          CMake, and
+          plain Makefiles.
+        
+      
+      
+        
+          Adding GTK-Doc specific files to version control and deciding which
+          files to ignore (see 
+            Integration with version control systems).
+        
+      
+    
+
+    
+      The following sections assume we work on a project called
+      meep.
+      This project contains two packages (or modules),
+      a library called libmeep and an end-user app
+      called meeper.
+    
+
+    
+      Setting up a skeleton documentation
+
+      
+        A common convention is to place documentation into a folder called
+        docs inside your top-level project directory.
+        We usually distinguish between reference
+        documentation intended for developers and an
+        user manual intended for end-users.
+        Again the convention is to have separate folders for both.
+        We usually place the reference documentation in a folder named
+        reference and the end-user manual in a folder named
+        help as.
+
+        According to the above convention the documentation for our
+        libmeep package would be placed into:
+        docs/reference/libmeep.
+
+        For packages with just one library or application
+        the documentation could also be placed directly into
+        docs/reference.
+
+        It is not mandatory to use the above convention, but if you
+        choose to use a different directory structure you must adjust
+        your build system configuration to match your directory
+        structure.
+      
+
+      
+        In the following sections we will assume a directory structure
+        for our meep project that uses the above
+        conventions.
+
+        
+          Example directory structure of <emphasis>meep</emphasis>
+            project
+          
+        
+      
+    
+
+    
+      Integration with Autotools
+      
+        Integration of GTK-Doc into an autotools-based build system requires the
+        following steps:
+      
+      
+        
+          
+            Ensure that gtkdocize is run once before
+            the configure script. If an
+            autogen.sh script is present, adjust it to
+            check for GTK-Doc and add a call to
+            gtkdocize.
+          
+
+          
+            The main purpose of gtkdocize is to
+            make the gtk-doc.make Makefile and the
+            gtk-doc.m4 macro definition file available
+            to the build system, either by copying or linking it
+            into the project.
+          
+        
+        
+          
+            Add the necessary autoconf macros to
+            configure.ac to enable GTK-Doc in your build
+            system to allow configuration of GTK-Doc via the generated
+            configure script.
+          
+          
+            Among others with registers the --enable-gtk-doc
+            option with the configure script.
+          
+        
+        
+          
+            Create an automake script for each
+            application or library in your project. In the example used in this
+            documentation this step applies to both meeper and
+            libmeep.
+          
+        
+      
+
+      
+        In the following sections, we will perform the above steps in reverse
+        order. We start with the automake scripts
+        and work our way up to configure.ac and
+        autogen.sh.
+        Then we show how enable Gtk-Doc in the build system and
+        how to build the documentation.
+      
+
+      
+        Integration with automake
+
+        
+          First copy the Makefile.am from the
+          examples sub-directory of the
+          
+            gtkdoc-sources
+          to your project's reference documentation directory (e.g.
+          docs/reference/<package>).
+          A local copy should be available under e.g.
+          /usr/share/doc/gtk-doc-tools/examples/Makefile.am.
+          If you have multiple packages repeat this for each one.
+        
+
+        
+          
+            Do not forget to add each Makefile.am
+            to the AC_CONFIG_FILES macro in
+            configure.ac. For
+            docs/reference/libmeep/Makefile.am you will
+            need to add the entry
+            docs/reference/libmeep/Makefile
+            to AC_CONFIG_FILES.
+          
+        
+
+        
+          
+            Example directory structure with <filename>Makefiles.am</filename>
+          
+          
+meep/
+  docs/
+    reference/  # reference documentation
+      libmeep/
+        Makefile.am
+      meeper/
+        Makefile.am
+    help/       # optional: user manual
+      meeper/
+  src/
+    libmeep/
+    meeper/
+
+        
+
+        
+          Next, you need to customize the copied Makefiles
+          and provide values for the various parameters in each
+          Makefile.am.
+
+          All settings have a comment above them that describes their purpose
+          and how to customize the setting.
+
+          Most settings are used to supply extra flags to the respective tools
+          to which they apply. Every tool
+          has a variable of the form 
+          (e.g. the tool gtkdoc-mkhtml has
+          an option named MKHTML_OPTIONS).
+
+          All the tools support  to list the supported
+          options.
+        
+
+        
+          The following list explains the most relevant options. Check the
+          example Makefile.am for additional options.
+
+          
+            
+              
+                 is used to provide the name of the
+                package that is being documentated (e.g. meeper, or
+                libmeep).
+              
+            
+            
+              
+                
+                is used to specify the location
+                of source directory which GTK-Doc searches for your API
+                documentation. This will usually be
+                
+                  DOC_SOURCE_DIR=$(top_srcdir)/src
+                
+                or a sub-directory of that directory.
+              
+            
+
+            
+              
+                
+                and
+                
+                are used for dependencies. Each option take a file-glob (e.g.
+                HFILE_GLOB=$(top_srcdir)/src/*.c).
+                The documentation will be rebuilt if any of the matched files
+                change.
+              
+            
+
+            
+              
+                
+                allows to specify extra header files
+                to include when scanning for API documentation, which are not
+                found under DOC_SOURCE_DIR (e.g. 
+                EXTRA_HFILES=$(top_srcdir}/contrib/extra.h).
+              
+            
+
+            
+              
+                
+                allows to specify header files
+                or directories to ignore when scanning for API documentation.
+                Use the basename of the file or directory (e.g. 
+                IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder).
+              
+            
+
+            
+              
+                
+                allows to specify images files which
+                will be copied into the html/ directory of
+                the generated documentation.
+                If your API documentation includes any images they need to be
+                added to this
+                option (e.g. 
+                HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png).
+              
+            
+
+            
+              
+                
+                allows to specify extra files
+                that are included by
+                $(DOC_MAIN_SGML_FILE)
+                (e.g. 
+                content_files=running.xml building.xml changes-2.0.xml).
+              
+            
+
+            
+              
+                
+                allows to specify files
+                where gtk-doc abbreviations such as
+                #GtkWidget
+                are expanded (e.g. 
+                expand_content_files=running.xml).
+              
+            
+          
+        
+
+      
+
+      
+        Integration with autoconf
+
+        
+          Integration with autoconf is very simple
+          and includes one required step and an additional optional
+          (but recommended) step.
+
+          The first step is to add the GTK_DOC_CHECK macro
+          to your configure.ac script. This registers
+          several configure options to enable GTK-Doc and allows you
+          to set default arguments for gtkdocize.
+        
+
+        
+          
+            Make sure that the GTK_DOC_CHECK macro is not indented.
+            The macro must start at the beginning of the line and should not
+            start with whitespace.
+          
+        
+
+        
+          The second step is to add the AC_CONFIG_MACRO_DIR(m4)
+          to your configure.ac. This is not required
+          but helps gtkdocize to automatically copy
+          the macro definition (e.g gtk-doc.m4) which
+          contains the GTK_DOC_CHECK macro to your
+          project's macro directory. Without this, the GTK_DOC_CHECK macro
+          might not be found and you would need to explicitly tell the
+          aclocal tool where to find the macro
+          definition file.
+        
+
+        
+          Minimal integration with autoconf
+            
+          
+        
+
+        
+          The above example works, but will require all developers to have
+          gtk-doc installed. A better way is to make building the documentation
+          optional as shown in the next example:
+
+          
+            Integration with optional gtk-doc dependency
+            
+          
+        
+
+        
+          The first argument is used to check for the Gtk-Doc version at
+          configure time. The 2nd, optional argument is used by
+          gtkdocize.
+          The GTK_DOC_CHECK macro also adds several configure
+          switches:
+        
+
+        
+          --with-html-dir=PATH : path to installed docs
+          --enable-gtk-doc : use gtk-doc to build documentation [default=no]
+          --enable-gtk-doc-html : build documentation in html format [default=yes]
+          --enable-gtk-doc-pdf : build documentation in pdf format [default=no]
+        
+
+        
+          
+            GTK-Doc is disabled by default! Remember to pass the option
+             to the next
+            configure run. Otherwise pregenerated documentation is installed
+            (which makes sense for users but not for developers).
+          
+        
+
+        
+          After all changes to configure.ac are made,
+          update the configure file. This can be done by
+          re-running autogen.sh.
+        
+      
+
+      
+        Integration with autogen
+
+        
+          Most projects will have an autogen.sh script to
+          setup the build infrastructure after the project was checked out from
+          a version control system (such as git or svn). GTK-Doc comes with a
+          script called gtkdocize which can be used
+          to copy the necessary files needed by Gtk-Doc to the source directory.
+        
+
+        
+          It should be run before autoreconf, autoheader, automake or autoconf.
+        
+
+        
+          Running gtkdocize from autogen.sh
+            
+          
+        
+
+        
+          
+            Conditionally run gtkdocize from autogen.sh
+            /dev/null)
+if test $? -ne 0; then
+  echo "No gtk-doc support found. You can't build the docs."
+else
+  $GTKDOCIZE || exit 1
+fi
+]]>
+          
+        
+
+        
+          When running gtkdocize it copies
+          gtk-doc.make to your project root (or any
+          directory specified by the  option).
+        
+
+        
+          gtkdocize checks your
+          configure.ac script for
+          the GTK_DOC_CHECK macro.
+          The GTK_DOC_CHECK macro can be used to pass
+          extra arguments to the gtkdocize script.
+          the 2nd parameter in the GTK_DOC_CHECK macro.
+        
+
+        
+          Alternatively, additional arguments can also be passed to
+          gtkdocize via the
+          GTKDOCIZE_FLAGS environment variable, or by
+          directly specifying them to gtkdocize
+          in autogen.sh.
+        
+
+      
+
+      
+        Executing GTK-Doc from the Build System
+
+        
+          After the previous steps it's time to run the build. First we need to
+          rerun autogen.sh. If this script runs configure
+          for you, then give it the  option.
+          Otherwise manually run configure with this option
+          afterwards.
+        
+        
+          The first make run generates several additional files in the doc-directories.
+          The important ones are:
+          <package>.types,
+          <package>-docs.xml (in the past .sgml),
+          <package>-sections.txt.
+        
+        
+          Running the doc build
+            
+          
+        
+
+        
+          Now you can point your browser to
+          docs/reference/<package>/index.html.
+          With this initial setup you will only see a very simple document.
+          The next chapter will teach you how to add API documentation to your
+          code via special comment blocks. The Chapter afterwards introduces
+          additional files and shows how to
+          edit the master template to
+          add additional chapters and sections to your documentation files.
+        
+
+      
+
+    
+
+    
+      Integration with CMake build systems
+
+      
+        GTK-Doc now provides a GtkDocConfig.cmake module
+        (and the corresponding GtkDocConfigVersion.cmake
+        module). This provides a gtk_doc_add_module
+        command that you can set in your CMakeLists.txt
+        file.
+      
+
+      
+        The following example shows how to use this command.
+        Example of using GTK-Doc from CMake
+          
+        
+      
+    
+
+    
+      Integration with plain makefiles or other build systems
+
+      
+        In the case one does not want to use automake and therefore
+        gtk-doc.mak one will need to call the gtkdoc tools
+        in the right order in own makefiles (or other build tools).
+      
+
+      
+        Documentation build steps
+          
+gtkdoc-scangobj --module=$(DOC_MODULE)
+gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=
+// xml files have changed
+mkdir html
+cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
+gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
+]]>
+        
+      
+
+      
+        One will need to look at the Makefile.am and
+        gtk-doc.mak to pick the extra options needed.
+      
+    
+
+    
+      Integration with version control systems
+
+      
+        As a rule of thumb, it's the files you edit which should go under
+        version control. For typical projects it's these files:
+        <package>.types,
+        <package>-docs.xml (in the past .sgml),
+        <package>-sections.txt,
+        Makefile.am.
+      
+      
+        Files in the xml/ and html/
+        directories should not go under version control. Neither should any of
+        the .stamp files.
+      
+    
+
+  
+
+  
+    Documenting the code
+
+    
+      GTK-Doc uses source code comment with a special syntax for code documentation.
+      Further it retrieves information about your project structure from other
+      sources. During the next section you will find all information about the
+      syntax of the comments.
+    
+
+    
+      The GTK-Doc scanner can handle the majority of C headers fine. In the
+      case of receiving warnings from the scanner that look like a special
+      case, one can hint GTK-Doc to skip over them.
+      GTK-Doc comment block
+        
+      
+    
+
+    
+      Limitations
+      
+        Note, that GTK-Doc's supports
+        #ifndef(__GTK_DOC_IGNORE__) but not
+        #if !defined(__GTK_DOC_IGNORE__) or other combinations.
+      
+    
+
+    
+
+    
+      Documentation comments
+
+      
+        A multiline comment that starts with an additional '*' marks a
+        documentation block that will be processed by the GTK-Doc tools.
+        GTK-Doc comment block
+          
+        
+      
+
+      
+        The 'identifier' is one line with the name of the item the comment is
+        related to. The	syntax differs a little depending on the item.
+        (TODO add table showing identifiers)
+      
+
+      
+        The 'documentation' block is also different for each symbol type. Symbol
+        types that get parameters such as functions or macros have the parameter
+        description first followed by a blank line (just a '*').
+        Afterwards follows the detailed description. All lines (outside program
+        listings and CDATA sections) just containing a ' *' (blank-asterisk) are
+        converted to paragraph breaks.
+        If you don't want a paragraph break, change that into ' *  '
+        (blank-asterisk-blank-blank). This is useful in preformatted text (code
+        listings).
+      
+
+      
+        
+          When documenting code, describe two aspects:
+          
+             
+               
+                 What it is: The name for a class or function can sometimes
+                 be misleading for people coming from a different background.
+                
+             
+             
+               
+                 What it does: Tell about common uses. Put it in relation
+                 with the other API.
+               
+             
+           
+        
+      
+
+      
+        One advantage of hyper-text over plain-text is the ability to have links
+        in the document. Writing the correct markup for a link can be tedious
+        though. GTK-Doc comes to help by providing several useful abbreviations.
+        
+          
+            
+              Use function() to refer to functions or macros which take arguments.
+            
+          
+          
+            
+              Use @param to refer to parameters. Also use this when referring to
+              parameters of other functions, related to the one being described.
+            
+          
+          
+            
+              Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
+            
+          
+          
+            
+              Use #symbol to refer to other types of symbol, e.g. structs and
+              enums and macros which don't take arguments.
+            
+          
+          
+            
+              Use #Object::signal to refer to a GObject signal.
+            
+          
+          
+            
+              Use #Object:property to refer to a GObject property.
+            
+          
+          
+            
+              Use #Struct.field to refer to a field inside a structure and
+              #GObjectClass.foo_bar() to refer to a vmethod.
+            
+          
+        
+      
+
+      
+        
+          If you need to use the special characters '<', '>', '()', '@',
+          '%', or '#' in your documentation without GTK-Doc changing them you
+          can use the XML entities "&lt;", "&gt;", "&lpar;",
+          "&rpar;", "&commat;", "&percnt;" and "&num;"
+          respectively or escape them with a backslash '\'.
+        
+      
+
+      
+        DocBook can do more than just links. One can also have lists,
+        examples, headings, and images. As of version 1.20, the
+        preferred way is to use a subset of the basic text formatting
+        syntax called
+        Markdown.
+        On older GTK-Doc versions any documentation that includes
+        Markdown will be rendered as is.  For example, list items will
+        appear as lines starting with a dash.
+      
+
+      
+        While markdown is now preferred one can mix both. One limitation here is
+        that one can use docbook xml within markdown, but markdown within
+        docbook xml is not supported.
+      
+
+      
+        In older GTK-Doc releases, if you need support for additional
+        formatting, you would need to enable the usage of docbook
+        XML tags inside doc-comments by putting 
+        (or ) in the variable
+        MKDB_OPTIONS inside Makefile.am.
+      
+
+      
+        GTK-Doc comment block using Markdown
+          
+ * GtkWidget *label = gtk_label_new ("Gorgeous!");
+ * ]|
+ */
+]]>
+        
+      
+
+      
+        More examples of what markdown tags are supported can be found in the
+        GTK+ Documentation Markdown Syntax Reference.
+      
+
+      
+        
+          As already mentioned earlier GTK-Doc is for documenting public API. Thus
+          one cannot write documentation for static symbols. Nevertheless it is good
+          to comment those symbols too. This helps other developers to understand
+          your code.
+          Therefore we recommend to comment these using normal comments (without the
+          2nd '*' in the first line).
+          If later the function needs to be made public, all one needs to do is to
+          add another '*' in the comment block and insert the symbol name at the
+          right place inside the sections file.
+        
+      
+    
+
+    
+      Documenting sections
+
+      
+        Each section of the documentation contains information about one class
+        or module. To introduce the component one can write a section block.
+        The short description is also used inside the table of contents.
+        All the @fields are optional.
+      
+
+      
+        Section comment block
+          
+        
+      
+
+      
+        
+          SECTION:<name>
+          
+            
+              The name links the section documentation to the respective part in
+              the <package>-sections.txt file. The
+              name given here should match the <FILE> tag in the
+              <package>-sections.txt file.
+            
+          
+        
+        
+          @short_description
+          
+            
+              A one line description of the section, that later will appear after
+              the links in the TOC and at the top of the section page.
+            
+          
+        
+        
+          @title
+          
+            
+              The section title defaults to <name> from the SECTION
+              declaration. It can be overridden with the @title field.
+            
+          
+        
+        
+          @section_id
+          
+            
+              Overrides the use of title as a section identifier. For GObjects
+              the <title> is used as a section_id and for other sections
+              it is <MODULE>-<title>.
+            
+          
+        
+        
+          @see_also
+          
+            
+              A list of symbols that are related to this section.
+            
+          
+        
+        
+          @stability
+          
+            
+              An informal description of the stability level this API has.
+              We recommend the use of one of these terms:
+              
+                
+                  
+                    Stable
+                    - The intention of a Stable interface is to enable arbitrary
+                    third parties to develop applications to these interfaces,
+                    release them, and have confidence that they will run on all
+                    minor releases of the product (after the one in which the
+                    interface was introduced, and within the same major release).
+                    Even at a major release, incompatible changes are expected
+                    to be rare, and to have strong justifications.
+                  
+                
+                
+                  
+                    Unstable
+                    - Unstable interfaces are experimental or transitional.
+                    They are typically used to give outside developers early
+                    access to new or rapidly changing technology, or to provide
+                    an interim solution to a problem where a more general
+                    solution is anticipated.
+                    No claims are made about either source or binary
+                    compatibility from one minor release to the next.
+                  
+                
+                
+                  
+                    Private
+                    - An interface that can be used within the GNOME stack
+                    itself, but that is not documented for end-users. Such
+                    functions should only be used in specified and documented
+                    ways.
+                  
+                
+                
+                  
+                    Internal
+                    - An interface that is internal to a module and does not
+                    require end-user documentation. Functions that are
+                    undocumented are assumed to be Internal.
+                  
+                
+              
+            
+          
+        
+        
+          @include
+          
+            
+              The #include files to show in the section
+              synopsis (a comma separated list), overriding the global
+              value from the section
+              file or command line.  This item is optional.
+            
+          
+        
+        
+          @image
+          
+            
+              The image to display at the top of the reference page for this
+              section.  This will often be some sort of a diagram to illustrate
+              the visual appearance of a class or a diagram of its relationship
+              to other classes.  This item is optional.
+            
+          
+        
+      
+
+      
+        
+          To avoid unnecessary recompilation after doc-changes put the section
+          docs into the c-source where possible.
+        
+      
+
+    
+
+    
+      Documenting symbols
+
+      
+        Each symbol (function, macro, struct, enum, signal and property) is
+        documented in a separate block. The block is best placed close to the
+        definition of the symbols so that it is easy to keep them in sync.
+        Thus functions are usually documented in the c-source and macros,
+        structs and enums in the header file.
+      
+
+      General tags
+
+        
+          You can add versioning information to all documentation elements to tell
+          when an API was introduced, or when it was deprecated.
+        
+
+        Versioning Tags
+          Since:
+            
+              
+                Description since which version of the code the API is available.
+              
+            
+          
+          Deprecated:
+            
+              
+                Paragraph denoting that this function should no be used anymore.
+                The description should point the reader to the new API.
+              
+            
+          
+        
+
+        
+          You can also add stability information to all documentation elements
+          to indicate whether API stability is guaranteed for them for all
+          future minor releases of the project.
+        
+
+        
+          The default stability level for all documentation elements can be set
+          by passing the  argument to
+          gtkdoc-mkdb with one of the values below.
+        
+
+        Stability Tags
+          Stability: Stable
+            
+              
+                Mark the element as stable. This is for public APIs which are
+                guaranteed to remain stable for all future minor releases of the
+                project.
+              
+            
+          
+          Stability: Unstable
+            
+              
+                Mark the element as unstable. This is for public APIs which are
+                released as a preview before being stabilised.
+              
+            
+          
+          Stability: Private
+            
+              
+                Mark the element as private. This is for interfaces which can be
+                used by tightly coupled modules, but not by arbitrary third
+                parties.
+              
+            
+          
+        
+
+        General tags
+          
+        
+      
+
+      Annotations
+
+        
+          Documentation blocks can contain annotation-tags. These tags will be
+          rendered with tooltips describing their meaning. The tags are used by
+          gobject-introspection to generate language bindings. A detailed list
+          of the supported tags can be found on
+          the wiki.
+        
+
+        Annotations
+          
+        
+      
+
+      Function comment block
+
+        
+          Please remember to:
+          
+            
+              
+                Document whether returned objects, lists, strings, etc, should be
+                freed/unrefed/released.
+              
+            
+            
+              
+                Document whether parameters can be NULL, and what happens if they are.
+              
+            
+            
+              
+                Mention interesting pre-conditions and post-conditions where appropriate.
+              
+            
+          
+        
+
+        
+          Gtk-doc assumes all symbols (macros, functions) starting with '_' are
+          private. They are treated like static functions.
+        
+
+        Function comment block
+          
+        
+
+        Function tags
+          Returns:
+            
+              
+                Paragraph describing the returned result.
+              
+            
+          
+          @...:
+            
+              
+                In case the function has variadic arguments, you should use this
+                tag (@Varargs: does also work for historic reasons).
+              
+            
+          
+        
+
+      
+
+      Property comment block
+
+        Property comment block
+          
+        
+
+      
+
+      Signal comment block
+
+        
+          Please remember to:
+          
+            
+              
+                Document when the signal is emitted and whether it is emitted before
+                or after other signals.
+              
+            
+            
+              
+                Document what an application might do in the signal handler.
+              
+            
+          
+        
+
+        Signal comment block
+          
+        
+
+      
+
+      Struct comment block
+        Struct comment block
+          
+        
+
+        
+          Use /*< private >*/ before the private struct fields
+          you want to hide. Use /*< public >*/ for the reverse
+          behaviour.
+        
+
+        
+          If the first field is "g_iface", "parent_instance" or "parent_class"
+          it will be considered private automatically and doesn't need to be
+          mentioned in the comment block.
+        
+
+        
+          Struct comment blocks can also be used for GObjects and GObjectClasses.
+          It is usually a good idea to add a comment block for a class, if it has
+          vmethods (as this is how they can be documented). For the GObject
+          itself one can use the related section docs, having a separate block
+          for the instance struct would be useful if the instance has public
+          fields. One disadvantage here is that this creates two index entries
+          of the same name (the structure and the section).
+        
+
+      
+
+      Enum comment block
+        Enum comment block
+          */
+  SOMETHING_COUNT
+} Something;
+]]>
+        
+
+        
+          Use /*< private >*/ before the private enum values
+          you want to hide. Use /*< public >*/ for the reverse
+          behaviour.
+        
+
+      
+    
+
+
+    
+      Inline program documentation
+      
+         You can document programs and their commandline interface using inline
+         documentation.
+      
+
+      
+      Tags
+
+      PROGRAM
+
+      
+      
+         Defines the start of a program documentation.
+      
+      
+      
+
+      
+      @short_description:
+      
+      
+         Defines a short description of the program. (Optional)
+      
+      
+      
+
+      
+      @synopsis:
+      
+      
+         Defines the arguments, or list of arguments that the program can take.
+         (Optional)
+      
+      
+      
+
+      
+      @see_also:
+      
+      
+          See Also manual page section. (Optional)
+      
+      
+      
+
+      
+      @arg:
+      
+      
+          Argument(s) passed to the program and their description. (Optional)
+      
+      
+      
+
+      
+      Description:
+      
+      
+          A longer description of the program.
+      
+      
+      
+
+      
+      Returns:
+      
+      
+          Specify what value(s) the program returns. (Optional)
+      
+      
+      
+
+      
+
+      
+        Example of program documentation.
+        Program documentation block
+        
+        
+
+      
+    
+
+    
+      Useful DocBook tags
+
+      
+        Here are some DocBook tags which are most useful when documenting the
+        code.
+      
+
+      
+        To link to another section in the GTK docs:
+
+        
+          Hash Tables
+]]>
+        
+        The linkend is the SGML/XML id on the top item of the page you want to link to.
+        For most pages this is currently the part ("gtk", "gdk", "glib") and then
+        the page title ("Hash Tables"). For widgets it is just the class name.
+        Spaces and underscores are converted to '-' to conform to SGML/XML.
+      
+
+      
+        To refer to an external function, e.g. a standard C function:
+        
+          ...
+]]>
+        
+      
+
+      
+        To include example code:
+        
+          
+  Using a GHashTable.
+  
+      ...
+  
+
+]]>
+        
+        or possibly this, for very short code fragments which don't need a title:
+        
+          
+  
+  ...
+  
+
+]]>
+        
+        In both cases, the language attribute is optional and is used as a hint
+        to the syntax highlighting engine (pygments for html output).
+        For the latter GTK-Doc also supports an abbreviation:
+        
+          
+  ...
+]|
+]]>
+        
+      
+
+      
+        To include bulleted lists:
+        
+          
+  
+    
+      ...
+    
+  
+  
+    
+      ...
+    
+  
+
+]]>
+        
+      
+
+      
+        To include a note which stands out from the text:
+        
+          
+  
+    Make sure you free the data after use.
+  
+
+]]>
+        
+      
+
+      
+        To refer to a type:
+        
+          unsigned char
+]]>
+        
+      
+
+      
+        To refer to an external structure (not one described in the GTK docs):
+        
+          XFontStruct
+]]>
+        
+      
+
+      
+        To refer to a field of a structure:
+        
+          len
+]]>
+        
+      
+
+      
+        To refer to a class name, we could possibly use:
+        
+          GtkWidget
+]]>
+        
+        but you'll probably be using #GtkWidget instead (to automatically create
+        a link to the GtkWidget page - see the abbreviations).
+      
+
+      
+        To emphasize text:
+        
+          This is important
+]]>
+        
+      
+
+      
+        For filenames use:
+        
+          /home/user/documents
+]]>
+        
+      
+
+      
+        To refer to keys use:
+        
+          ControlL
+]]>
+        
+      
+
+    
+  
+
+  
+    Filling the extra files
+
+    
+      There are a couple of extra files, that need to be maintained along with
+      the inline source code comments:
+      <package>.types,
+      <package>-docs.xml (in the past .sgml),
+      <package>-sections.txt.
+    
+
+    
+      Editing the types file
+
+      
+        If your library or application includes GObjects, you want
+        their signals, arguments/parameters and position in the hierarchy to be
+        shown in the documentation. All you need to do, is to list the
+        xxx_get_type functions together with their include
+        inside the <package>.types file.
+      
+
+      
+        Example <package>.types file
+          
+
+gtk_accel_label_get_type
+gtk_adjustment_get_type
+gtk_alignment_get_type
+gtk_arrow_get_type
+]]>
+        
+      
+
+      
+        Since GTK-Doc 1.8 gtkdoc-scan can generate this list for you.
+        Just add "--rebuild-types" to SCAN_OPTIONS in Makefile.am. If you
+        use this approach you should not dist the types file nor have it under version control.
+      
+
+    
+
+    
+      Editing the master document
+
+      
+        GTK-Doc produces documentation in DocBook SGML/XML. When processing the
+        inline source comments, the GTK-Doc tools generate one documentation
+        page per class or module as a separate file. The master document
+        includes them and place them in an order.
+      
+
+      
+        While GTK-Doc creates a template master document for you, later runs will
+        not touch it again. This means that one can freely structure the
+        documentation. That includes grouping pages and adding extra pages.
+        GTK-Doc has now a test suite, where also the master-document is recreated from scratch.
+        Its a good idea to look at this from time to time to see if there are
+        some new goodies introduced there.
+      
+
+      
+        
+          Do not create tutorials as extra documents. Just write extra chapters.
+          The benefit of directly embedding the tutorial for your library into
+          the API documentation is that it is easy to link for the tutorial to
+          symbol documentation. Apart chances are higher that the tutorial gets
+          updates along with the library.
+        
+      
+
+      
+        So what are the things to change inside the master document? For a start
+        is only a little. There are some placeholders (text in square brackets)
+        there which you should take care of.
+      
+
+      
+        Master document header
+          
+  MODULENAME Reference Manual
+  
+    for MODULENAME [VERSION]
+    The latest version of this documentation can be found on-line at
+    http://[SERVER]/MODULENAME/.
+  
+
+
+
+  [Insert title here]
+]]>
+        
+      
+
+      
+        In addition a few option elements are created in commented form. You can
+        review these and enable them as you like.
+      
+
+      
+        Optional part in the master document
+          
+  -->
+]]>
+        
+      
+
+      
+        Finally you need to add new section whenever you introduce one. The
+        gtkdoc-check tool will
+        remind you of newly generated xml files that are not yet included into
+        the doc.
+      
+
+      
+        Including generated sections
+          
+    my library
+      
+      ...
+]]>
+        
+      
+
+    
+
+    
+      Editing the section file
+
+      
+        The section file is used to organise the documentation output by
+        GTK-Doc. Here one specifies which symbol belongs to which module or
+        class and control the visibility (public or private).
+      
+
+      
+        The section file is a plain text file with tags delimiting sections.
+        Blank lines are ignored and lines starting with a '#' are treated as
+        comment lines.
+      
+
+      
+        
+          While the tags make the file look like xml, it is not. Please do not
+          close tags like <SUBSECTION>.
+        
+      
+
+      
+        Including generated sections
+          libmeep/meep.h
+
+
    
+meepapp
+MeepApp
+MeepApp
+
+MEEP_APP
+...
+MeepAppClass
+meep_app_get_type
+
    
+]]>    
+            
+          
+
+      
+        The <FILE> ... </FILE> tag is used to specify the file name,
+        without any suffix. For example, using '<FILE>gnome-config</FILE>'
+        will result in the section declarations being output in the template
+        file tmpl/gnome-config.sgml, which will be
+        converted into the DocBook XML file xml/gnome-config.sgml
+        or the DocBook XML file xml/gnome-config.xml.
+        (The name of the HTML file is based on the module name and the section
+        title, or for GObjects it is based on the GObjects class name converted
+        to lower case).
+      
+
+      
+        The <TITLE> ... </TITLE> tag is used to specify the title of
+        the section. It is only useful before the templates (if used) are
+        initially created, since the title set in the template file overrides
+        this. Also if one uses SECTION comment in the sources, this is obsolete.
+      
+
+      
+        You can group items in the section by using the <SUBSECTION> tag.
+        Currently it outputs a blank line between subsections in the synopsis
+        section.
+        You can also use <SUBSECTION Standard> for standard GObject
+        declarations (e.g. the functions like g_object_get_type and macros like
+        G_OBJECT(), G_IS_OBJECT() etc.).
+        Currently these are left out of the documentation.
+        You can also use <SUBSECTION Private> for private declarations
+        which will not be output (it is a handy way to avoid warning messages
+        about unused declarations).
+        If your library contains private types which you don't want to appear in
+        the object hierarchy and the list of implemented or required interfaces,
+        add them to a Private subsection.
+        Whether you would place GObject and GObjectClass like structs in public
+        or Standard section depends if they have public entries (variables,
+        vmethods).
+      
+
+      
+        You can also use <INCLUDE> ... </INCLUDE> to specify the
+        #include files which are shown in the synopsis sections.
+        It contains a comma-separate list of #include files, without the angle
+        brackets. If you set it outside of any sections, it acts for all
+        sections until the end of the file. If you set it within a section, it
+        only applies to that section.
+      
+
+        
+
+      
+
+  
+    Controlling the result
+
+    
+      A GTK-Doc run generates report files inside the documentation directory.
+      The generated files are named:
+      <package>-undocumented.txt,
+      <package>-undeclared.txt and
+      <package>-unused.txt.
+      All those are plain text files that can be viewed and postprocessed easily.
+    
+
+    
+      The <package>-undocumented.txt file starts with
+      the documentation coverage summary. Below are two sections divided by
+      blank lines. The first section lists undocumented or incomplete symbols.
+      The second section does the same for section docs. Incomplete entries are
+      those, which have documentation, but where e.g. a new parameter has been
+      added.
+    
+
+    
+      The <package>-undeclared.txt file lists symbols
+      given in the <package>-sections.txt but not
+      found in the sources. Check if they have been removed or if they are
+      misspelled.
+    
+
+    
+      The <package>-unused.txt file lists symbol
+      names, where the GTK-Doc scanner has found documentation, but does not
+      know where to put it. This means that the symbol has not yet been added to
+      the <package>-sections.txt file.
+    
+
+    
+      
+        Enable or add the  line in Makefile.am.
+        If at least GTK-Doc 1.9 is installed, this will run sanity checks during
+        make check run.
+      
+    
+
+    
+      One can also look at the files produced by the source code scanner:
+      <package>-decl-list.txt and
+      <package>-decl.txt. The first one can be
+      compared with the section file if that is manually maintained. The second
+      lists all declarations from the headers. If a symbol is missing one could
+      check if this file contains it.
+    
+
+    
+      If the project is GObject based, one can also look into the files produced
+      by the object scanner:
+      <package>.args.txt,
+      <package>.hierarchy.txt,
+      <package>.interfaces.txt,
+      <package>.prerequisites.txt and
+      <package>.signals.txt. If there are missing
+      symbols in any of those, one can ask GTK-Doc to keep the intermediate
+      scanner file for further analysis, by running it as
+      GTK_DOC_KEEP_INTERMEDIATE=1 make.
+    
+  
+
+  
+    Modernizing the documentation
+
+    
+      GTK-Doc has been around for quite some time. In this section we list new
+      features together with the version since when it is available.
+    
+
+    
+      GTK-Doc 1.9
+
+      
+        When using xml instead of sgml, one can actually name the master
+        document <package>-docs.xml.
+      
+
+      
+        This version supports 
+        in Makefile.am. When this is enabled, the
+        <package>-sections.txt is autogenerated and
+        can be removed from the vcs. This only works nicely for projects that
+        have a very regular structure (e.g. each .{c,h} pair will create new
+        section). If one organize a project close to that updating a manually
+        maintained section file can be as simple as running
+        meld <package>-decl-list.txt <package>-sections.txt.
+      
+
+      
+        Version 1.8 already introduced the syntax for documenting sections in
+        the sources instead of the separate files under tmpl.
+        This version adds options to switch the whole doc module to not use the
+        extra tmpl build step at all, by using 
+        in configure.ac. If you don't have a tmpl
+        checked into your source control system and haven't yet switched, just
+        add the flag to configure.ac and you are done.
+      
+    
+
+    
+      GTK-Doc 1.10
+
+      
+        This version supports  in
+        Makefile.am. When this is enabled, the
+        <package>.types is autogenerated and can be
+        removed from the vcs. When using this feature it is important to also
+        setup the IGNORE_HFILES in
+        Makefile.am for code that is build conditionally.
+      
+    
+
+    
+      GTK-Doc 1.16
+
+      
+        This version includes a new tool called gtkdoc-check. This tool can run
+        a set of sanity checks on your documentation. It is enabled by adding
+        these lines to the end of Makefile.am.
+        Enable gtkdoc-check
+          
+        
+      
+    
+
+    
+      GTK-Doc 1.20
+
+      
+        Version 1.18 brought some initial markdown support. Using markdown in
+        doc comments is less intrusive than writing docbook xml. This version
+        improves a lot on this and add a lot more styles. The section that
+        explains the comment syntax
+        has all the details.
+      
+    
+
+    
+      GTK-Doc 1.25
+
+      
+        The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent,
+        containing entities for e.g. package_name and package_version. You can
+        use this e.g. in the main xml file to avoid hardcoding the version
+        number. Below is an example that shows how the entity file is included
+        in the master template and how the entities are used.
+        The entities can also be used in all
+        generated files, GTK-Doc will use the same xml header in generated xml
+        files.
+        Use pre-generated entities
+          
+
+  
+  %gtkdocentities;
+]>
+
+  
+    &package_name; Reference Manual
+    
+      for &package_string;.
+      The latest version of this documentation can be found on-line at
+      http://[SERVER]/&package_name;/.
+    
+  
+]]>
+        
+      
+    
+  
+
+  
+    Documenting other interfaces
+
+    
+      So far we have been using GTK-Doc to document the API of code. The next
+      sections contain suggestions how the tools can be used to document other
+      interfaces too.
+    
+
+    
+      Command line options and man pages
+
+      
+        As one can generate man pages for a docbook refentry as well, it sounds
+        like a good idea to use it for that purpose. This way the interface is
+        part of the reference and one gets the man-page for free.
+      
+
+      
+        Document the tool
+
+        
+          Create one refentry file per tool. Following
+          our example we would call it
+          meep/docs/reference/meeper/meep.xml. For the xml
+          tags that should be used and can look at generated file in the xml
+          subdirectory as well as examples e.g. in glib.
+        
+      
+
+      
+        Adding the extra configure check
+
+        
+          Extra configure checks
+            
+          
+        
+      
+
+      
+        Adding the extra makefile rules
+
+        
+          Extra configure checks
+            
+          
+        
+      
+    
+
+    
+      DBus interfaces
+
+      
+        (FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html,
+http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)
+      
+    
+
+  
+
+  
+    Frequently asked questions
+
+    
+      
+      Question
+      Answer
+      
+        No class hierarchy.
+        
+          The objects xxx_get_type() function has not been
+          entered into the <package>.types file.
+        
+      
+      
+        Still no class hierarchy.
+        
+          Missing or wrong naming in <package>-sections.txt
+          file (see explanation).
+        
+      
+      
+        Damn, I have still no class hierarchy.
+        
+          Is the object name (name of the instance struct, e.g. GtkWidget)
+          part of the normal section (don't put this into Standard or Private
+          subsections).
+        
+      
+      
+        No symbol index.
+        
+          Does the <package>-docs.{xml,sgml} contain a
+          index that xi:includes the generated index?
+        
+      
+      
+        Symbols are not linked to their doc-section.
+        
+          Is the doc-comment using the correct markup (added #,% or ())?
+          Check if the gtkdoc-fixxref warns about unresolvable xrefs.
+        
+      
+      
+        A new class does not appear in the docs.
+        
+          Is the new page xi:included from
+          <package>-docs.{xml,sgml}.
+        
+      
+      
+        A new symbol does not appear in the docs.
+        
+          Is the doc-comment properly formatted. Check for spelling mistakes in
+          the begin of the comment. Check if the gtkdoc-fixxref warns about
+          unresolvable xrefs. Check if the symbol is correctly listed in the
+          <package>-sections.txt in a public subsection.
+        
+      
+      
+        A type is missing from the class hierarchy.
+        
+          If the type is listed in <package>.hierarchy
+          but not in xml/tree_index.sgml then double check
+          that the type is correctly placed in the <package>-sections.txt.
+          If the type instance (e.g. GtkWidget) is not listed or
+          incidentally marked private it will not be shown.
+        
+      
+      
+        I get foldoc links for all gobject annotations.
+        
+          Check that xml/annotation-glossary.xml is
+          xi:included from <package>-docs.{xml,sgml}.
+        
+      
+
+      
+      
+        Parameter described in source code comment block but does not exist
+        Check if the prototype in the header has different parameter names as in the source.
+      
+
+      
+      
+        multiple "IDs" for constraint linkend: XYZ
+        Symbol XYZ appears twice in <package>-sections.txt file.
+      
+      
+        Element typename in namespace '' encountered in para, but no template matches.
+        
+      
+    
+  
+
+  
+    Tools related to gtk-doc
+
+    
+      GtkDocPlugin - a Trac GTK-Doc
+      integration plugin, that adds API docs to a trac site and integrates with
+      the trac search.
+    
+    
+      Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since
+      tags in the API to determine the minimum required version.
+    
+
+  
+
+  
+  &FDL;
+
+    
+
diff --git a/gtk-doc-for-gtk4/help/manual/ChangeLog b/gtk-doc-for-gtk4/help/manual/ChangeLog
new file mode 100644
index 0000000000..c0306cee7a
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/manual/ChangeLog
@@ -0,0 +1,157 @@
+2010-01-25 Sweta Kothari  
+
+        * gu/gu.po: Updated Gujarati translation
+
+2009-04-09 Jorge Gonzalez  
+
+	* es/es.po: Updated Spanish translation
+
+2009-04-07  Simos Xenitellis  
+
+	* el/el.po: Added Greek translation.
+	* Makefile.am: Added el.
+
+2009-03-25  Philip Withnall  
+
+	* Makefile.am:
+	* en_GB/en_GB.po: Added British English translation by Jen Ockwell
+	 and myself.
+
+2009-03-24 Jorge Gonzalez  
+
+	* es/es.po: Updated Spanish translation
+
+2009-03-23  Jorge Gonzalez  
+
+	* es/es.po: Updated Spansih translation
+
+2009-03-22  Jorge Gonzalez  
+
+	* es/es.po: Updated Spansih translation
+
+2009-03-17  Jorge Gonzalez  
+
+        * es/es.po: Updated Spansih translation
+
+2009-03-16  Mario Blättermann  
+
+	* de/de.po: Added initial German translation
+	* Makefile.am: Added de to DOC_LINGUAS
+
+2009-03-15  Jorge Gonzalez  
+
+	* es/es.po: Added initial Spanish translation
+	* Makefile.am: Added es to DOC_LINGUAS
+
+2008-09-08  Rob Bradford  
+
+	* C/gtk-doc-manual.xml:
+	Correct the command for non-tmpl Makefile and highlight it within a
+	 block.
+
+2007-08-14  Marc-Andre Lureau  
+
+	* GNOME doc-utils migration, ChangeLog moved to help/manual
+
+2007-07-23  Stefan Kost  
+
+	* gtk-doc-manual.xml:
+	  Tell about $(DOC_MODULE)-undeclared.txt.
+
+2007-07-15  Stefan Kost  
+
+	* gtk-doc-manual.xml:
+	Bump version. Add more markup. Tell that one can use toolname --help to
+	get the allowed opetion for Makefile.am. Improve 'how does it work' section.
+
+2007-06-11  Damon Chaplin  
+
+	* gtk-doc-manual.xml: added tip about using entities like # to
+	use a '#' without gtk-doc changing it. (Part of #445596)
+
+2007-01-21  Damon Chaplin  
+
+	* gtk-doc-manual.xml: document "@include:" tag. #395023
+
+2006-12-10  J.H.M. Dassen (Ray) 
+
+	* gtk-doc-manual.xml: Spelling fixes.
+
+2006-10-13  Damon Chaplin  
+
+	* gtk-doc-manual.xml: use "GNOME" instead of "Gnome". (#352160)
+
+2006-03-24  Stefan Kost  
+
+	* gtk-doc-manual.xml:
+	correct format of new shortcuts
+
+2006-03-21  Stefan Kost  
+
+	* gtk-doc-manual.xml:
+	document signal and property link short cuts
+
+2005-12-09  Stefan Kost  
+
+	* gtk-doc-manual-C.omf.in:
+	* gtk-doc-manual.xml:
+	  added more details about doc-comments
+	  added section about revision control systems
+
+2005-09-07  Stefan Kost  
+
+	* gtk-doc-manual.xml:
+	  integrated most of the notes from the text files under doc/*.txt
+
+2005-08-24  Stefan Kost  
+
+	* gtk-doc-manual.xml:
+          more notes in the faq
+          setup chapter is nearly complete
+          more notes about doc comment format
+
+2005-08-15  Stefan Kost  
+
+	* .cvsignore:
+	* ChangeLog:
+	* Makefile:
+	* Makefile.am:
+	* fdl-appendix.xml:
+	* gtk-doc-manual-C.omf.in:
+	* gtk-doc-manual.xml:
+          reanimated gtkdoc manual
+          added new chapters
+
+2004-05-07	Geert Stappers 
+
+	* README: new file.
+	* gtk-doc-manual.sgml: Deleted.
+	* fdl-appendix.sgml: Deleted.
+
+2004-05-06	Geert Stappers 
+
+	* gtk-doc-manual.xml: repaired the crossreference to FDL
+
+	* Makefile: new file, to "document" the build process.
+
+2004-05-06	Keith Sharp 
+
+	* gtk-doc-manual.xml: New file, XML version of
+	  gtk-doc-manual.sgml
+	* fdl-appendix.xml: New file, XML version of
+	  fdl-appendix.sgml
+
+2000-11-26	Dan Mueth 
+
+	* gtk-doc-manual.sgml: Committing changes made by
+	Chris Lyttle .  (Text for Chapter 1)
+
+2000-11-25	Dan Mueth 
+
+	* gtk-doc-manual.sgml: Put part of the outline into SGML.
+	  Chris plans to put rest of outline in here and start
+	  writing.
+	* fdl-appendix.sgml: The FDL in SGML.  We will probably post
+	  these on the web as a single document (book) so we will
+	  need the FDL to be included as an appendix.
+
diff --git a/gtk-doc-for-gtk4/help/manual/LINGUAS b/gtk-doc-for-gtk4/help/manual/LINGUAS
new file mode 100644
index 0000000000..4b0e383737
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/manual/LINGUAS
@@ -0,0 +1,17 @@
+# Please keep this list sorted alphabetically.
+#
+bn_IN
+cs
+de
+el
+en_GB
+es
+fr
+gl
+gu
+pt_BR
+sl
+sv
+ta
+te
+zh_CN
\ No newline at end of file
diff --git a/gtk-doc-for-gtk4/help/manual/Makefile.am b/gtk-doc-for-gtk4/help/manual/Makefile.am
new file mode 100644
index 0000000000..b56fa4d585
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/manual/Makefile.am
@@ -0,0 +1,17 @@
+if HAVE_YELP_TOOLS
+@YELP_HELP_RULES@
+endif
+
+HELP_ID = gtk-doc-manual
+
+HELP_FILES = \
+    index.docbook \
+    fdl-appendix.xml
+
+HELP_LINGUAS = bn_IN cs de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN
+
+CLEANFILES = $(_HELP_LC_FILES) $(_HELP_LC_STAMPS) $(_HELP_MOFILES)
+
+GITIGNOREFILES = ??_??/$(HELP_ID).xml ??/$(HELP_ID).xml
+
+-include $(top_srcdir)/git.mk
diff --git a/gtk-doc-for-gtk4/help/manual/bn_IN/bn_IN.po b/gtk-doc-for-gtk4/help/manual/bn_IN/bn_IN.po
new file mode 100644
index 0000000000..cf2c73aa36
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/manual/bn_IN/bn_IN.po
@@ -0,0 +1,1341 @@
+# translation of bn_IN.po to Bengali INDIA
+# Runa Bhattacharjee , 2010.
+msgid ""
+msgstr ""
+"Project-Id-Version: bn_IN\n"
+"POT-Creation-Date: 2010-01-27 10:26+0000\n"
+"PO-Revision-Date: 2010-02-02 15:40+0530\n"
+"Last-Translator: Runa Bhattacharjee \n"
+"Language-Team: Bengali INDIA \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Generator: KBabel 1.11.4\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+#: C/gtk-doc-manual.xml:12(title)
+msgid "GTK-Doc Manual"
+msgstr "GTK-Doc সহায়িকা"
+
+#: C/gtk-doc-manual.xml:13(edition) C/gtk-doc-manual.xml:92(revnumber)
+msgid "1.12"
+msgstr "১.১২"
+
+#: C/gtk-doc-manual.xml:14(para)
+msgid "User manual for developers with instructions of GTK-Doc usage."
+msgstr "GTK-Doc ব্যবহারের নির্দেশাবলী সহ, ডিভেলপরদের উদ্দেশ্যে নির্মিত সহায়িকা।"
+
+#: C/gtk-doc-manual.xml:17(firstname)
+msgid "Chris"
+msgstr "ক্রিস"
+
+#: C/gtk-doc-manual.xml:18(surname)
+msgid "Lyttle"
+msgstr "লিটল"
+
+#: C/gtk-doc-manual.xml:21(email)
+msgid "chris@wilddev.net"
+msgstr "chris@wilddev.net"
+
+#: C/gtk-doc-manual.xml:26(firstname)
+msgid "Dan"
+msgstr "ড্যান"
+
+#: C/gtk-doc-manual.xml:27(surname)
+msgid "Mueth"
+msgstr "মুয়েথ"
+
+#: C/gtk-doc-manual.xml:30(email)
+msgid "d-mueth@uchicago.edu"
+msgstr "d-mueth@uchicago.edu"
+
+#: C/gtk-doc-manual.xml:35(firstname)
+msgid "Stefan"
+msgstr "স্টেফান"
+
+#: C/gtk-doc-manual.xml:36(surname)
+msgid "Kost"
+msgstr "কোস্ট"
+
+#: C/gtk-doc-manual.xml:39(email)
+msgid "ensonic@users.sf.net"
+msgstr "ensonic@users.sf.net"
+
+#: C/gtk-doc-manual.xml:45(publishername)
+msgid "GTK-Doc project"
+msgstr "GTK-Doc প্রজেক্ট"
+
+#: C/gtk-doc-manual.xml:46(email)
+msgid "gtk-doc-list@gnome.org"
+msgstr "gtk-doc-list@gnome.org"
+
+#: C/gtk-doc-manual.xml:49(year)
+msgid "2000, 2005, 2007-2009"
+msgstr "২০০০, ২০০৫, ২০০৭-২০০৯"
+
+#: C/gtk-doc-manual.xml:50(holder)
+msgid "Dan Mueth and Chris Lyttle and Stefan Kost"
+msgstr "ড্যান মুয়েথ ও ক্রিস লিটল ও স্টেফান কোস্ট"
+
+#: C/gtk-doc-manual.xml:61(para)
+msgid "Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:69(para)
+msgid "Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:80(revnumber)
+msgid "1.14"
+msgstr "১.১৪"
+
+#: C/gtk-doc-manual.xml:81(date)
+msgid "19 December 2009"
+msgstr "১৯ ডিসেম্বর ২০০৯"
+
+#: C/gtk-doc-manual.xml:82(authorinitials) C/gtk-doc-manual.xml:88(authorinitials) C/gtk-doc-manual.xml:94(authorinitials)
+msgid "sk"
+msgstr "sk"
+
+#: C/gtk-doc-manual.xml:83(revremark)
+msgid "development version"
+msgstr "ডিভেলপমেন্ট সংস্করণ"
+
+#: C/gtk-doc-manual.xml:86(revnumber)
+msgid "1.13"
+msgstr "১.১৩"
+
+#: C/gtk-doc-manual.xml:87(date) C/gtk-doc-manual.xml:93(date)
+msgid "18 December 2009"
+msgstr "১৮ ডিসেম্বর ২০০৯"
+
+#: C/gtk-doc-manual.xml:89(revremark)
+msgid "broken tarball update"
+msgstr "ক্ষতিগ্রস্ত tarball আপডেট করা হয়েছে"
+
+#: C/gtk-doc-manual.xml:95(revremark)
+msgid "new tool features and bugfixes"
+msgstr "নতুন সরঞ্জামের বৈশিষ্ট্য ও সংশোধিত বাগের তথ্য"
+
+#: C/gtk-doc-manual.xml:98(revnumber)
+msgid "1.11"
+msgstr "১.১১"
+
+#: C/gtk-doc-manual.xml:99(date)
+msgid "16 Novemebr 2008"
+msgstr "১৬ ডিসেম্বর ২০০৯"
+
+#: C/gtk-doc-manual.xml:100(authorinitials)
+msgid "mal"
+msgstr "mal"
+
+#: C/gtk-doc-manual.xml:101(revremark)
+msgid "GNOME doc-utils migration"
+msgstr "GNOME doc-utils মাইগ্রেশন"
+
+#: C/gtk-doc-manual.xml:110(title)
+msgid "Introduction"
+msgstr "ভূমিকা"
+
+#: C/gtk-doc-manual.xml:112(para)
+msgid "This chapter introduces GTK-Doc and gives an overview of what it is and how it is used."
+msgstr "এই অধ্যায়ে GTK-Doc সম্বন্ধে প্রারম্ভিক তথ্য ও এটির ব্যবহার ও মূল বিষয়বস্তু সম্পর্কে তথ্য উপস্থিত করা হয়েছে।"
+
+#: C/gtk-doc-manual.xml:118(title)
+msgid "What is GTK-Doc?"
+msgstr "GTK-Doc কী?"
+
+#: C/gtk-doc-manual.xml:120(para)
+msgid "GTK-Doc is used to document C code. It is typically used to document the public API of libraries, such as the GTK+ and GNOME libraries. But it can also be used to document application code."
+msgstr "GTK-Doc-র সাহায্যে C কোডের জন্য নথি তৈরি করা হয়। বিভিন্ন লাইব্রেরি যেমন GTK+ ও GNOME লাইব্রেরির পাবলিক API সম্বন্ধীয় নথি তৈরি করার জন্য এটি ব্যবহৃত হয়। অ্যাপ্লিকেশনের কোড সম্পর্কিত তথ্য লেখার জন্যও এটি ব্যবহার করা হয়।"
+
+#: C/gtk-doc-manual.xml:128(title)
+msgid "How Does GTK-Doc Work?"
+msgstr "GTK-Doc কীভাবে ব্যবহার করা যাবে?"
+
+#: C/gtk-doc-manual.xml:130(para)
+msgid "GTK-Doc works by using documentation of functions placed inside the source files in specially-formatted comment blocks, or documentation added to the template files which GTK-Doc uses (though note that GTK-Doc will only document functions that are declared in header files; it won't produce output for static functions)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:137(para)
+msgid "GTK-Doc consists of a number of perl scripts, each performing a different step in the process."
+msgstr "GTK-Doc-র মধ্যে অনেকগুলি perl স্ক্রিপ্ট উপস্থিত রয়েছে ও প্রতিটি স্ক্রিপ্ট দ্বারা সম্পর্ণ প্রক্রিয়ার একটি ভিন্ন ধাপের কর্ম সঞ্চালন করা হয়।"
+
+#: C/gtk-doc-manual.xml:142(para)
+msgid "There are 5 main steps in the process:"
+msgstr "এই প্রক্রিয়ার মধ্যে ৫-টি প্রধান ধাপ উপস্থিত রয়েছে:"
+
+#: C/gtk-doc-manual.xml:149(para)
+msgid "Writing the documentation. The author fills in the source files with the documentation for each function, macro, union etc. (In the past information was entered in generated template files, which is not recommended anymore)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:159(para)
+msgid "Gathering information about the code.gtkdoc-scan scans the header files of the code looking for declarations of functions, macros, enums, structs, and unions. It creates the file <module>-decl-list.txt containg a list of the declarations, placing them into sections according to which header file they are in. On the first run this file is copied to <module>-sections.txt The author can rearrange the sections, and the order of the declarations within them, to produce the final desired order. The second file it generates is <module>-decl.txt. This file contains the full declarations found by the scanner. If for some reason one would like some sybols to show up in the docs, where the full declaration cannot be found by th scanner or the declaration should appear differently, one can place enties similar to the ones in <module>-decl.txt into <module>-overrides.txt. gtkdoc-scanobj can also be used to dynamically query a library about any GtkObject subclasses it exports. It saves information about each object's position in the class hierarchy and about any GTK Args and Signals it provides."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:184(para)
+msgid "Generating the \"template\" files.gtkdoc-mktmpl creates a number of files in the tmpl/ subdirectory, using the information gathered in the first step. (Note that this can be run repeatedly. It will try to ensure that no documentation is ever lost.)"
+msgstr "\"template\" ফাইল নির্মাণ। প্রথম ধাপে সংগ্রহ করা তথ্যের ভিত্তিতে gtkdoc-mktmpl দ্বারা tmpl/ সাব-ডিরেক্টরির মধ্যে বেশ কয়েকটি ফাইল নির্মাণ করা হয়। (উল্লেখ্য, কোনো নথিপত্র হারিয়ে না ফেলার লক্ষ্যে, এই কাজটি পুনরাবৃত্তি করা হতে পারে।)"
+
+#: C/gtk-doc-manual.xml:193(para)
+msgid "Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep documentation in the code. gtkdocize supports now a  option that chooses a makefile that skips tmpl usage totally. If you have never changed file in tmpl by hand, please remove the dir (e.g. from version control system)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:205(para)
+msgid "Generating the SGML/XML and HTML/PDF.gtkdoc-mkdb turns the template files into SGML or XML files in the sgml/ or xml/ subdirectory. If the source code contains documentation on functions, using the special comment blocks, it gets merged in here. If there are no tmpl files used it only reads takes docs from sources and introspection data."
+msgstr "SGML/XML ও HTML/PDF নির্মাণের প্রণালী। sgml/ অথবা xml/ সাব-ডিরেক্টরির মধ্যে উপস্থিত SGML অথবা XML ফাইলগুলিকে gtkdoc-mkdb দ্বারা টেমপ্লেট ফাইল রূপে পরিবর্তন করা হয়। সোর্স কোডের মধ্যে ফাংশান সংক্রান্ত নতিপত্র উপস্থিত থাকলে, বিশেষ কমেন্ট ব্লক প্রয়োগ করে সংশ্লিষ্ট অংশগুলি এইখানে অন্তর্ভুক্ত করা হয়। কোনো tmpl ফাইল ব্যবহার না করা হলে, শুধুমাত্র সোর্স থেকে নথি ও বিশ্লেষণের তথ্য সংগ্রহ করা হয়।"
+
+#: C/gtk-doc-manual.xml:215(para)
+msgid "gtkdoc-mkhtml turns the SGML/XML files into HTML files in the html/ subdirectory. Likewise gtkdoc-mkpdf turns the SGML/XML files into a PDF docuemnt called <package>.pdf."
+msgstr "gtkdoc-mkhtml দ্বারা SGML/XML ফাইলগুলিকে HTML html/ সাব-ডিরেক্টরির মধ্যে HTML ফাইল রূপে পরিবর্তন করা হয়। একই পদ্ধতিতে  gtkdoc-mkpdf দ্বারা SGML/XML ফাইলগুলিকে PDF <package>.pdf নামক একটি PDF নথিতে রূপান্তর করা হয়।"
+
+#: C/gtk-doc-manual.xml:221(para)
+msgid "Files in sgml/ or xml/ and html/ directories are always overwritten. One should never edit them directly."
+msgstr "sgml/ অথবা xml/ ও html/ ডিরেক্টরির মধ্যে উপস্থিত ফাইলগুলি সর্বদা নতুন করে লেখা হবে। এই ফাইলগুলি সরাসরি পরিবর্তন করা উচিত নয়।"
+
+#: C/gtk-doc-manual.xml:229(para)
+msgid "Fixing up cross-references between documents. After installing the HTML files, gtkdoc-fixxref can be run to fix up any cross-references between separate documents. For example, the GTK+ documentation contains many cross-references to types documented in the GLib manual. When creating the source tarball for distribution, gtkdoc-rebase turns all external links into web-links. When installing distributed (pregenerated) docs the same application will try to turn links back to local links (where those docs are installed)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:247(title)
+msgid "Getting GTK-Doc"
+msgstr "GTK-Doc প্রাপ্ত করার প্রণালী"
+
+#: C/gtk-doc-manual.xml:250(title)
+msgid "Requirements"
+msgstr "আবশ্যক মান"
+
+#: C/gtk-doc-manual.xml:251(para)
+msgid "Perl v5 - the main scripts are in Perl."
+msgstr "Perl v5 - প্রধান স্ক্রিপ্টগুলি Perl-এ লেখা হয়েছে।"
+
+#: C/gtk-doc-manual.xml:254(para)
+msgid "DocBook DTD v3.0 - This is the DocBook SGML DTD. http://www.ora.com/davenport"
+msgstr "DocBook DTD v3.0 - এটি DocBook SGML DTD। http://www.ora.com/davenport"
+
+#: C/gtk-doc-manual.xml:258(para)
+msgid "Jade v1.1 - This is a DSSSL processor for converting SGML to various formats. http://www.jclark.com/jade"
+msgstr "Jade v1.1 - SGML-কে বিভিন্ন বিন্যাসে পরিবর্তনের জন্য ব্যবহৃত এটি একটি DSSSL প্রসেসর। http://www.jclark.com/jade"
+
+#: C/gtk-doc-manual.xml:262(para)
+msgid "Modular DocBook Stylesheets This is the DSSSL code to convert DocBook to HTML (and a few other formats). It's used together with jade. I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour the program code listings/declarations, and to support global cross-reference indices in the generated HTML. http://nwalsh.com/docbook/dsssl"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:271(para)
+msgid "docbook-to-man - if you want to create man pages from the DocBook. I've customized the 'translation spec' slightly, to capitalise section headings and add the 'GTK Library' title at the top of the pages and the revision date at the bottom. There is a link to this on http://www.ora.com/davenport NOTE: This does not work yet."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:282(title)
+msgid "Installation"
+msgstr "ইনস্টলেশনের প্রণালী"
+
+#: C/gtk-doc-manual.xml:283(para)
+msgid "There is no standard place where the DocBook Modular Stylesheets are installed."
+msgstr "DocBook মডিউলার স্টাইল-শিট ইনস্টল করার কোনো প্রমিত স্থান উপস্থিত নেই।"
+
+#: C/gtk-doc-manual.xml:286(para)
+msgid "GTK-Doc's configure script searches these 3 directories automatically:"
+msgstr "GTK-Doc-র কনফিগার স্ক্রিপ্ট দ্বারা স্বয়ংক্রিয়ভাবে নিম্নলিখিত তিনটি ডিরেক্টরির মধ্যে অনুসন্ধান করা হয়:"
+
+#: C/gtk-doc-manual.xml:289(para)
+msgid " /usr/lib/sgml/stylesheets/nwalsh-modular  (used by RedHat)"
+msgstr " /usr/lib/sgml/stylesheets/nwalsh-modular  (RedHat দ্বারা ব্যবহৃত)"
+
+#: C/gtk-doc-manual.xml:292(para)
+msgid " /usr/lib/dsssl/stylesheets/docbook  (used by Debian)"
+msgstr " /usr/lib/dsssl/stylesheets/docbook  (Debian দ্বারা ব্যবহৃত)"
+
+#: C/gtk-doc-manual.xml:295(para)
+msgid " /usr/share/sgml/docbkdsl  (used by SuSE)"
+msgstr " /usr/share/sgml/docbkdsl  (SuSE দ্বারা ব্যবহৃত)"
+
+#: C/gtk-doc-manual.xml:298(para)
+msgid "If you have the stylesheets installed somewhere else, you need to configure GTK-Doc using the option:  --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR> "
+msgstr "স্টাইল-শিটগুলি অন্য কোনো স্থানে ইনস্টল করা হয়ে থাকলে, নিম্নলিখিত বিকল্প সহয়োগে GTK-Doc কনফিগার করতে হবে:  --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR> "
+
+#: C/gtk-doc-manual.xml:322(title)
+msgid "About GTK-Doc"
+msgstr "GTK-Doc পরিচিতি"
+
+#: C/gtk-doc-manual.xml:324(para) C/gtk-doc-manual.xml:338(para)
+msgid "(FIXME)"
+msgstr "(FIXME)"
+
+#: C/gtk-doc-manual.xml:328(para)
+msgid "(History, authors, web pages, license, future plans, comparison with other similar systems.)"
+msgstr "(পূর্ববর্তী তথ্য, লেখক, ওয়েব-পেজ, লাইসেন্স, ভবিষ্যতের প্রকল্প, অন্যান্য সমতূল্য সিস্টেমের সাথে তূলনা।)"
+
+#: C/gtk-doc-manual.xml:336(title)
+msgid "About this Manual"
+msgstr "এই সহায়িকার পরিচিতি"
+
+#: C/gtk-doc-manual.xml:342(para)
+msgid "(who it is meant for, where you can get it, license)"
+msgstr "(উদ্দিষ্ট পাঠকবৃন্দ, প্রাপ্তির স্থান, লাইসেন্স)"
+
+#: C/gtk-doc-manual.xml:351(title)
+msgid "Setting up your project"
+msgstr "প্রজেক্ট প্রস্তুত করার প্রণালী"
+
+#: C/gtk-doc-manual.xml:353(para)
+msgid "The next sections describe what steps to perform to integrate GTK-Doc into your project. Theses section assume we work on a project called 'meep'. This project contains a library called 'libmeep' and an end-user app called 'meeper'."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:361(title)
+msgid "Setting up a skeleton documentation"
+msgstr "নথির একটি পরিকাঠামো নির্ধারণের প্রণালী"
+
+#: C/gtk-doc-manual.xml:363(para)
+msgid "Under your top-level project directory create folders called docs/reference (this way you can also have docs/help for end-user documentation). It is recommended to create another subdirectory with the name of the doc-package. For packages with just one library this step is not necessary."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:372(title)
+msgid "Example directory structure"
+msgstr "ডিরেক্টরির বিন্যাসের উদাহরণ"
+
+#: C/gtk-doc-manual.xml:370(para)
+msgid "This can then look as show below: "
+msgstr "নিম্নলিখিত উদাহরণের অনুরূপ হবে: "
+
+#: C/gtk-doc-manual.xml:390(title) C/gtk-doc-manual.xml:397(title)
+msgid "Integration with autoconf"
+msgstr "autoconf সহযোগে একত্রিত করার প্রণালী"
+
+#: C/gtk-doc-manual.xml:392(para)
+msgid "Very easy! Just add one line to your configure.ac script."
+msgstr "এই কাজ অতিমাত্রায় সহজ! configure.ac স্ক্রিপ্টের মধ্যে একটি পংক্তি যোগ করুন।"
+
+#: C/gtk-doc-manual.xml:407(para)
+msgid "The first argument is used to check for the gtkdocversion at configure time. The 2nd, optional argument is used by gtkdocize. The GTK_DOC_CHECK macro also adds several configure switches:"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:413(para)
+msgid "--with-html-dir=PATH : path to installed docs"
+msgstr "--with-html-dir=PATH : ইনস্টল করা ডকুমেন্টের পাথ"
+
+#: C/gtk-doc-manual.xml:414(para)
+msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
+msgstr "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
+
+#: C/gtk-doc-manual.xml:415(para)
+msgid "--enable-gtk-doc-html : build documentation in html format [default=yes]"
+msgstr "--enable-gtk-doc-html : build documentation in html format [default=yes]"
+
+#: C/gtk-doc-manual.xml:416(para)
+msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
+msgstr "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
+
+#: C/gtk-doc-manual.xml:420(para)
+msgid "GTK-Doc is disabled by default! Remember to pass the option  to the next configure run. Otherwise pregenerated documentation is installed (which makes sense for users but not for developers)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:428(para)
+msgid "Furthermore it is recommended that you have the following line inside you configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:436(title)
+msgid "Preparation for gtkdocize"
+msgstr "gtkdocize-র প্রস্তুতি"
+
+#: C/gtk-doc-manual.xml:447(title)
+msgid "Integration with automake"
+msgstr "automake সহযোগে একত্রিত করার প্রণালী"
+
+#: C/gtk-doc-manual.xml:449(para)
+msgid "First copy the Makefile.am from the examples subdirectory of the gtkdoc-sources to your project's API documentation directory ( ./docs/reference/<package>). If you have multiple doc-packages repeat this for each one."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:456(para)
+msgid "The next step is to edit the setting inside the Makefile.am. All the settings have a comment above that describes their purpose. Most settings are extra flags passed to the respective tools. Every tool has a variable of the form . All the tools support  to list the supported parameters."
+msgstr ""
+
+#. FIXME: explain options ?
+#: C/gtk-doc-manual.xml:467(para)
+msgid "You may also want to enable GTK-Doc for the distcheckmake target. Just add then one-liner show in the next example to you top-level Makefile.am:"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:474(title)
+msgid "Enable GTK-Doc during make distcheck"
+msgstr "make distcheck-র সময় GTK-Doc সক্রিয় করুন"
+
+#: C/gtk-doc-manual.xml:486(title)
+msgid "Integration with autogen"
+msgstr "autogen সহযোগে একত্রিত করার প্রণালী"
+
+#: C/gtk-doc-manual.xml:488(para)
+msgid "Most projects will have an autogen.sh script to setup the build infrastructure after a checkout from version control system (such as cvs/svn/git). GTK-Doc comes with a tool called gtkdocize which can be used in such a script. It should be run before autoheader, automake or autoconf."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:497(title)
+msgid "Running gtkdocize from autogen.sh"
+msgstr "autogen.sh থেকে gtkdocsize সঞ্চালনার প্রণালী"
+
+#: C/gtk-doc-manual.xml:506(para)
+msgid "When running gtkdocize it copies gtk-doc.make to you project root (or any directory specified by the  option). If also check you configure script for the GTK_DOC_CHECK invocation."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:514(para)
+msgid "Historically GTK-Doc was gerating template files where developers entered the docs. this turned out to be not so good. Since a few version GTK-Doc could also get all the information from source comments. Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep documentation in the code. gtkdocize supports now a  option that chooses a makefile that skips tmpl usage totally. Besides adding the option directly to the command invocation, they can be added also to a environment variable called GTKDOCIZE_FLAGS or set as a 2nd parameter in GTK_DOC_CHECK macro in the configure script. If you have never changed file in tmpl by hand and migrating from older gtkdoc versions, please remove the dir (e.g. from version control system)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:530(title) C/gtk-doc-manual.xml:547(title)
+msgid "Running the doc build"
+msgstr "doc build সঞ্চালনার প্রণালী"
+
+#: C/gtk-doc-manual.xml:532(para)
+msgid "After the previous steps it's time to run the build. First we need to rerun autogen.sh. If this script runs configure for you, then give it the  option. Otherwise manually run configure with this option afterwards."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:539(para)
+msgid "The first make run generates several additional files in the doc-dirs. The important ones are: <package>.types, <package>-docs.sgml, <package>-sections.txt."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:556(para)
+msgid "Now you can point your browser to docs/reference/<package>/index.html. Yes, it's a bit disappointing still. But hang-on, during the next chapter we tell you how to fill the pages with life."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:564(title)
+msgid "Integration with version control systems"
+msgstr "ভার্সান কনট্রোল সিস্টেমের সাথে একত্রিত করার প্রণালী"
+
+#: C/gtk-doc-manual.xml:566(para)
+msgid "As a rule of the thumb, it's those files you edit, that should go under version control. For typical projects it's these files: <package>.types<package>-docs.sgml<package>-sections.txtMakefile.am"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:579(title)
+msgid "Documenting the code"
+msgstr "কোডের জন্য সহায়ক নথি লেখার প্রণালী"
+
+#: C/gtk-doc-manual.xml:581(para)
+msgid "GTK-Doc uses source code comment with a special syntax for code documentation. Further it retrieves information about your project structure from other sources. During the next section you find all information about the syntax of the comments."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:589(title)
+msgid "Documentation placement"
+msgstr "নথিপত্রের স্থাপনা"
+
+#: C/gtk-doc-manual.xml:590(para)
+msgid "In the past most documentation had to be filled into files residing inside the tmpl directory. This has the disadvantages that the information is often not updated and also that the file tend to cause conflicts with version control systems."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:596(para)
+msgid "The avoid the aforementioned problems we suggest putting the documentation inside the sources. This manual will only describe this way of documenting code."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:606(title)
+msgid "Documentation comments"
+msgstr "নথিপত্রের মধ্যে বিবৃতি"
+
+#: C/gtk-doc-manual.xml:611(title)
+msgid "GTK-Doc comment block"
+msgstr "GTK-Doc বিবৃতির অংশ"
+
+#: C/gtk-doc-manual.xml:608(para)
+msgid "A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the GTK-Doc tools. "
+msgstr ""
+
+#: C/gtk-doc-manual.xml:623(para)
+msgid "The 'identifier' is one line with the name of the item the comment is related to. The syntax differs a little depending on the item. (TODO add table showing identifiers)"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:629(para)
+msgid "The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program- listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:646(para)
+msgid "Use function() to refer to functions or macros which take arguments."
+msgstr "আর্গুমেন্ট গ্রহণকারী ফাংশান অথবা ম্যাক্রোর জন্য function() ব্যবহার করা হবে।"
+
+#: C/gtk-doc-manual.xml:651(para)
+msgid "Use @param to refer to parameters. Also use this when referring to parameters of other functions, related to the one being described."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:657(para)
+msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:662(para)
+msgid "Use #symbol to refer to other types of symbol, e.g. structs and enums and macros which don't take arguments."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:668(para)
+msgid "Use #Object::signal to refer to a GObject signal"
+msgstr "GObject signal-র জন্য #Object::signal ব্যবহার করুন"
+
+#: C/gtk-doc-manual.xml:673(para)
+msgid "Use #Object:property to refer to a GObject property"
+msgstr "GObject property-র জন্য #Object:property ব্যবহার করুন"
+
+#: C/gtk-doc-manual.xml:678(para)
+msgid "Use #Struct.field to refer to a field inside a structure."
+msgstr "স্ট্রাকচারের মধ্যে কোনো ফিল্ড চিহ্নিত করার জন্য #Struct.field প্রয়োগ করুন।"
+
+#: C/gtk-doc-manual.xml:640(para)
+msgid "One advantage of hyper-text over plain-text is the ability to have links in the document. Writing the correct markup for a link can be tedious though. GTK-Doc comes to help by providing several useful abbreviations. "
+msgstr "প্লেইন-টেক্সটের পরিবর্তে হাইপার-লিংক ব্যবহার করা হলে ডকুমেন্টের মধ্যে লিংক অন্তর্ভুক্ত করা সম্ভব হবে। কিন্তু লিংকের ক্ষেত্রে সঠিক markup লেখা পরিশ্রমের কাজ হতে পারে। GTK-Doc দ্বারা উপলব্ধ কয়েকটি সংক্ষিপ্ত শব্দের সাহায্যে এই কাজ হ্রাস করা যাবে। "
+
+#: C/gtk-doc-manual.xml:686(para)
+msgid "If you need to use the special characters '<', '>', '()', '@', '%', or '#' in your documentation without GTK-Doc changing them you can use the XML entities \"&lt;\", \"&gt;\", \"&lpar;\", \"&rpar;\", \"&commat;\", \"&percnt;\" and \"&num;\" respectively or escape them with a backslash '\\'."
+msgstr "নথির মধ্যে কিছু বিশেষ অক্ষর যেমন '<', '>', '()', '@', '%', অথবা '#' প্রভৃতি ব্যবহার করতে ইচ্ছুক হলে GTK-Doc দ্বারা এইগুলিকে পরিবর্তন করতে প্রতিরোধ করার জন্য যথাক্রমে \"&lt;\", \"&gt;\", \"&lpar;\", \"&rpar;\", \"&commat;\", \"&percnt;\" and \"&num;\" XML এনটিটিগুলি ব্যবহার করুন অথবা ব্যাক-স্ল্যাশ চিহ্ন '\\' সহযোগে এস্কেপ করানো আবশ্যক।"
+
+#: C/gtk-doc-manual.xml:695(para)
+msgid "DocBook can do more that just links. One can also have lists, tables and examples. To enable the usage of SGML/XML tags inside doc-comments you need to have  in the variable MKDB_OPTIONS inside Makefile.am."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:703(para)
+msgid "As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good to comment those symbols too. This helps other to understand you code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to add another '*' in the comment block and insert the symbol name at the right place inside the sections file."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:717(title)
+msgid "Documenting sections"
+msgstr "নথিপত্রের বিভাগ"
+
+#: C/gtk-doc-manual.xml:719(para)
+msgid "Each section of the documentation contains information about one class or module. To introduce the component one can write a section block. The short description is also used inside the table of contents. All the @fields are optional."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:727(title)
+msgid "Section comment block"
+msgstr "বিভাগ কমেন্ট ব্লক"
+
+#: C/gtk-doc-manual.xml:749(term)
+msgid "SECTION:<name>"
+msgstr "SECTION:<name>"
+
+#: C/gtk-doc-manual.xml:751(para)
+msgid "The name links the section documentation to the respective part in the <package>-sections.txt file. The name give here should match the <FILE> tag in the <package>-sections.txt file."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:760(term)
+msgid "@short_description"
+msgstr "@short_description"
+
+#: C/gtk-doc-manual.xml:762(para)
+msgid "A one line description of the section, that later will appear after the links in the TOC and at the top of the section page."
+msgstr "এক পংক্তি দ্বারা উল্লিখিত বিভাগের বিবরণ, সূচিপত্রের লিংকের পরে ও বিভাগের পৃষ্ঠার উপরে এই বিবরণ পরে প্রদর্শন করা হবে।"
+
+#: C/gtk-doc-manual.xml:769(term)
+msgid "@title"
+msgstr "@title"
+
+#: C/gtk-doc-manual.xml:771(para)
+msgid "The section title defaults to <name> from the SECTION declaration. It can be overridden with the @title field."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:778(term)
+msgid "@section_id"
+msgstr "@section_id"
+
+#: C/gtk-doc-manual.xml:780(para)
+msgid "Overrides the use of title as a section identifier. For GObjects the <title> is used as a section_id and for other section it is <MODULE>-<title>."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:788(term)
+msgid "@see_also"
+msgstr "@see_also"
+
+#: C/gtk-doc-manual.xml:790(para)
+msgid "A list of symbols that are related to this section.."
+msgstr "এই বিভাগ সম্বন্ধীয় সংকেতের তালিকা.."
+
+#: C/gtk-doc-manual.xml:796(term)
+msgid "@stability"
+msgstr "@stability"
+
+#: C/gtk-doc-manual.xml:803(para)
+msgid "Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:815(para)
+msgid "Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:827(para)
+msgid "Private - An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:836(para)
+msgid "Internal - An interface that is internal to a module and does not require end-user documentation. Functions that are undocumented are assumed to be Internal."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:798(para)
+msgid "A informal description of the stability level this API has. We recommend the use of one of these terms: "
+msgstr "চিহ্নিত API-র স্থায়ীত্বের পরিমানের আনুমানিক বিবরণ। চিহ্নিত কোনো অভিব্যক্তির ব্যবহার বাঞ্ছনীয়: "
+
+#: C/gtk-doc-manual.xml:848(term)
+msgid "@include"
+msgstr "@include"
+
+#: C/gtk-doc-manual.xml:850(para)
+msgid "The #include files to show in the section synopsis (a comma separated list), overriding the global value from the section file or command line. This item is optional."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:859(term)
+msgid "@image"
+msgstr "@image"
+
+#: C/gtk-doc-manual.xml:861(para)
+msgid "The image to display at the top of the reference page for this section. This will often be some sort of a diagram to illustrate the visual appearance of a class or a diagram of its relationship to other classes. This item is optional."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:872(para)
+msgid "To avoid unnecessary recompilation after doc-changes put the section docs into the c-source where possible."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:881(title)
+msgid "Documenting symbols"
+msgstr "নথিপত্রের সংকেত"
+
+#: C/gtk-doc-manual.xml:883(para)
+msgid "Each symbol (function, macro, struct, enum, signal and property) is documented in a separate block. The block is best placed close to the definition of the symbols so that it is easy to keep them in sync. Thus function are usually documented in the c-source and macros, struct and enum in the header file."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:891(title) C/gtk-doc-manual.xml:920(title)
+msgid "General tags"
+msgstr "সাধারণ ট্যাগ"
+
+#: C/gtk-doc-manual.xml:893(para)
+msgid "You can add versioning information to all documentation elements to tell when an api was introduced, or when it was deprecated."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:898(title)
+msgid "Versioning Tags"
+msgstr "সংস্করণ সংক্রান্ত ট্যাগ"
+
+#: C/gtk-doc-manual.xml:899(term)
+msgid "Since:"
+msgstr "প্রারম্ভ:"
+
+#: C/gtk-doc-manual.xml:901(para)
+msgid "Description since which version of the code the API is available."
+msgstr "API-টি কোডের কোন সংস্করণ থেকে উপলব্ধ রয়েছে সেটির বিবরণ।"
+
+#: C/gtk-doc-manual.xml:906(term)
+msgid "Deprecated:"
+msgstr "অবচিত:"
+
+#: C/gtk-doc-manual.xml:908(para)
+msgid "Paragraph denoting that this function should no be used anymore. The description should point the reader to the new API."
+msgstr "উল্লিখিত ফাংশান ব্যবহার না করার চিহ্নকারী অনুচ্ছেদ। এই বিবরণের সাহায্যে পাঠাকদেরকে নতুন API নির্দেশ করা হবে।"
+
+#: C/gtk-doc-manual.xml:916(para)
+msgid "(FIXME : Stability information)"
+msgstr "(FIXME : স্থায়ীত্ব সংক্রান্ত তথ্য)"
+
+#: C/gtk-doc-manual.xml:943(title) C/gtk-doc-manual.xml:979(title)
+msgid "Function comment block"
+msgstr "ফাংশান কমেন্টের ব্লক"
+
+#: C/gtk-doc-manual.xml:949(para)
+msgid "Document whether returned objects, lists, strings, etc, should be freed/unrefed/released."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:955(para)
+msgid "Document whether parameters can be NULL, and what happens if they are."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:960(para)
+msgid "Mention interesting pre-conditions and post-conditions where appropriate."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:945(para) C/gtk-doc-manual.xml:1042(para)
+msgid "Please remember to: "
+msgstr "অনুগ্রহ করে খেয়াল রাখবেন: "
+
+#: C/gtk-doc-manual.xml:967(para)
+msgid "Gtk-doc assumes all symbols (macros, functions) starting with '_' are private. They are treated like static functions."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:972(para)
+msgid "Also, take a look at gobject introspection annotation tags: http://live.gnome.org/GObjectIntrospection/Annotations"
+msgstr "উপরন্তু, gobject introspection annotation ট্যাগ দেখুন: http://live.gnome.org/GObjectIntrospection/Annotations"
+
+#: C/gtk-doc-manual.xml:1003(title)
+msgid "Function tags"
+msgstr "ফাংশান সংক্রান্ত ট্যাগ"
+
+#: C/gtk-doc-manual.xml:1004(term)
+msgid "Returns:"
+msgstr "প্রাপ্ত মান:"
+
+#: C/gtk-doc-manual.xml:1006(para)
+msgid "Paragraph describing the returned result."
+msgstr "প্রাপ্ত ফলাফলের বর্ণনা উপলব্ধকারী অনুচ্ছেদ।"
+
+#: C/gtk-doc-manual.xml:1011(term)
+msgid "@...:"
+msgstr "@...:"
+
+#: C/gtk-doc-manual.xml:1013(para)
+msgid "In case the function has variadic arguments, you should use this tag (@Varargs: does also work for historic reasons)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1023(title) C/gtk-doc-manual.xml:1025(title)
+msgid "Property comment block"
+msgstr "Property কমেন্টের ব্লক"
+
+#: C/gtk-doc-manual.xml:1040(title) C/gtk-doc-manual.xml:1059(title)
+msgid "Signal comment block"
+msgstr "Signal কমেন্টের ব্লক"
+
+#: C/gtk-doc-manual.xml:1046(para)
+msgid "Document when the signal is emitted and whether it is emitted before or after other signals."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1052(para)
+msgid "Document what an application might do in the signal handler."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1079(title) C/gtk-doc-manual.xml:1080(title)
+msgid "Struct comment block"
+msgstr "Struct কমেন্টের ব্লক"
+
+#: C/gtk-doc-manual.xml:1100(para)
+msgid "Use /*< private >*/ before the private struct fields you want to hide. Use /*< public >*/ for the reverse behavirour."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1108(title) C/gtk-doc-manual.xml:1109(title)
+msgid "Enum comment block"
+msgstr "Enum কমেন্টের ব্লক"
+
+#: C/gtk-doc-manual.xml:1130(para)
+msgid "Use /*< private >*/ before the private enum values you want to hide. Use /*< public >*/ for the reverse behavirour."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1140(title)
+msgid "Useful DocBook tags"
+msgstr "সুবিধাজনক DocBook ট্যাগ"
+
+#: C/gtk-doc-manual.xml:1142(para)
+msgid "Here are some DocBook tags which are most useful when documenting the code."
+msgstr "কোড নথিভুক্ত করার সময় সহায়ক কিছু DocBook ট্যাগ এইখানে উল্লেখ করা হল।"
+
+#: C/gtk-doc-manual.xml:1147(para)
+msgid "To link to another section in the GTK docs:  The linkend is the SGML/XML id on the top item of the page you want to link to. For most pages this is currently the part (\"gtk\", \"gdk\", \"glib\") and then the page title (\"Hash Tables\"). For widgets it is just the class name. Spaces and underscores are converted to '-' to conform to SGML/XML."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1163(para)
+msgid "To refer to an external function, e.g. a standard C function: "
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1174(para)
+msgid "To include example code:  or possibly this, for very short code fragments which don't need a title:  For the latter GTK-Doc also supports an abbreviation: "
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1208(para)
+msgid "To include bulleted lists: "
+msgstr "বুলেট চিহ্ন সহ তালিকা অন্তর্ভুক্ত করার জন্য ব্যবহার করুন: "
+
+#: C/gtk-doc-manual.xml:1230(para)
+msgid "To include a note which stands out from the text: "
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1245(para)
+msgid "To refer to a type: "
+msgstr "কোনো টাইপ উল্লেখ করা জন্য: "
+
+#: C/gtk-doc-manual.xml:1256(para)
+msgid "To refer to an external structure (not one described in the GTK docs): "
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1267(para)
+msgid "To refer to a field of a structure: "
+msgstr "কোনো স্ট্রাকচারের ফিল্ড উল্লেখ করার জন্য: "
+
+#: C/gtk-doc-manual.xml:1278(para)
+msgid "To refer to a class name, we could possibly use:  but you'll probably be using #GtkWidget instead (to automatically create a link to the GtkWidget page - see the abbreviations)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1291(para)
+msgid "To emphasize text: "
+msgstr "টেক্সট বিশেষভাবে উল্লেখ করার জন্য: "
+
+#: C/gtk-doc-manual.xml:1302(para)
+msgid "For filenames use: "
+msgstr "ফাইলের নামের জন্য ব্যবহার করুন: "
+
+#: C/gtk-doc-manual.xml:1313(para)
+msgid "To refer to keys use: "
+msgstr "কি উল্লেখ করার জন্য ব্যবহার করুন: "
+
+#: C/gtk-doc-manual.xml:1328(title)
+msgid "Filling the extra files"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1330(para)
+msgid "There are a couple of extra files, that need to be maintained along with the inline source code comments: <package>.types, <package>-docs.sgml, <package>-sections.txt."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1339(title)
+msgid "Editing the types file"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1341(para)
+msgid "If your library or application includes GtkObjects/GObjects, you want their signals, arguments/parameters and position in the hierarchy to be shown in the documentation. All you need to do, is to list the xxx_get_type functions together with their include inside the <package>.types file."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1350(title)
+msgid "Example types file snippet"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1364(para)
+msgid "Since GTK-Doc 1.8 gtkdoc-scan can generate this list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in Makefile.am. If you use this approach you should not dist the types file nor have it under version control."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1373(title)
+msgid "Editing the master document"
+msgstr "প্রধান নথি সম্পাদনা"
+
+#: C/gtk-doc-manual.xml:1375(para)
+msgid "GTK-Doc produces documentation in DocBook SGML/XML. When processing the inline source comments, the GTK-Doc tools generate one documentation page per class or module as a separate file. The master document includes them and place them in a order."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1382(para)
+msgid "While GTK-Doc creates a template master document for you, later run will not touch it again. This means that one can freely structure the documentation. That includes grouping pages and adding extra pages. GTK-Doc has now a test suite, where also the master-document is recreated from scratch. Its a good idea to look at this from time to time to see if there are some new goodies introduced there."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1392(para)
+msgid "Do not create tutorials as extra documents. Just write extra chapters. The benefit of directly embedding the tutorial for your library into the API documentation is that it is easy to link for the tutorial to symbol documentation. Apart chances are higher that the tutorial gets updates along with the library."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1401(para)
+msgid "So what are the things to change inside the master document? For a start is only a little. There are some placeholders (text in square brackets) there which you should take care of."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1408(title)
+msgid "Master document header"
+msgstr "প্রধা নথির হেডার"
+
+#: C/gtk-doc-manual.xml:1430(title)
+msgid "Editing the section file"
+msgstr "বিভাগের ফাইল সম্পাদনা"
+
+#: C/gtk-doc-manual.xml:1432(para)
+msgid "The section file is used to organise the documentation output by GTK-Doc. Here one specifies which symbol belongs to which module or class and control the visibility (public or private)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1438(para)
+msgid "The section file is a plain test file with xml like syntax (using tags). Blank lines are ignored and lines starting with a '#' are treated as comment lines."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1444(para)
+msgid "The <FILE> ... </FILE> tag is used to specify the file name, without any suffix. For example, using '<FILE>gnome-config</FILE>' will result in the section declarations being output in the template file tmpl/gnome-config.sgml, which will be converted into the DocBook SGML/XML file sgml/gnome-config.sgml or .DocBook XML file xml/gnome-config.xml. (The name of the html file is based on the module name and the section title, or for gobjects it is based on the gobjects class name converted to lower case)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1456(para)
+msgid "The <TITLE> ... </TITLE> tag is used to specify the title of the section. It is only useful before the templates (if used) are initially created, since the title set in the template file overrides this. Also if one uses SECTION comment in the sources, this is obsolete."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1463(para)
+msgid "You can group items in the section by using the <SUBSECTION> tag. Currently it outputs a blank line between subsections in the synopsis section. You can also use <SUBSECTION Standard> for standard GObject declarations (e.g. the functions like g_object_get_type and macros like G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out of the documentation. You can also use <SUBSECTION Private> for private declarations which will not be output (It is a handy way to avoid warning messages about unused declarations.). If your library contains private types which you don't want to appear in the object hierarchy and the list of implemented or required interfaces, add them to a Private subsection."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1479(para)
+msgid "You can also use <INCLUDE> ... </INCLUDE> to specify the #include files which are shown in the synopsis sections. It contains a comma-separate list of #include files, without the angle brackets. If you set it outside of any sections, it acts for all sections until the end of the file. If you set it within a section, it only applies to that section."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1493(title)
+msgid "Controlling the result"
+msgstr "ফলাফল নিয়ন্ত্রণের প্রণালী"
+
+#: C/gtk-doc-manual.xml:1495(para)
+msgid "A GTK-Doc run generates report files inside the documentation directory. The generated files are named: <package>-undocumented.txt, <package>-undeclared.txt and <package>-unused.txt. All those are plain text files that can be viewed and postprocessed easily."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1504(para)
+msgid "The <package>-undocumented.txt file starts with the documentation coverage summary. Below are two sections divided by blank lines. The first section lists undocumented or incomplete symbols. The second section does the same for section docs. Incomplete entries are those, which have documentation, but where e.g. a new parameter has been added."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1513(para)
+msgid "The <package>-undeclared.txt file lists symbols given in the <package>-sections.txt but not found in the sources. Check if they have been removed or if they are misspelled."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1520(para)
+msgid "The <package>-unused.txt file lists symbol names, where the GTK-Doc scanner has found documentation, but does not know where to put it. This means that the symbol has not yet been added to the <package>-sections.txt file."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1528(para)
+msgid "Enable or add the  line in Makefile.am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during make check run."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1535(para)
+msgid "One can also look at the files produced by the source code scanner: <package>-decl-list.txt and <package>-decl.txt. The first and can be compared with the section file if that is manualy maintained. The second lists all declarations fromt he headers If a symbol is missing one could check if this file contains it."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1544(para)
+msgid "If the project is GObject based, one can also look into the files produced by the object scanner: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt and <package>.signals.txt. If there are missing symbols in any of those, one can ask gtkdoc to keep the intermedia scanner file for further analysis, but running it as GTK_DOC_KEEP_INTERMEDIATE=1 make."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1559(title)
+msgid "Frequently asked question"
+msgstr "সাধারণ প্রশ্নোত্তর"
+
+#: C/gtk-doc-manual.xml:1563(segtitle)
+msgid "Question"
+msgstr "প্রশ্ন"
+
+#: C/gtk-doc-manual.xml:1564(segtitle)
+msgid "Answer"
+msgstr "উত্তর"
+
+#: C/gtk-doc-manual.xml:1566(seg)
+msgid "No class hierarchy."
+msgstr "কোনো ক্লাস অনুক্রম নেই।"
+
+#: C/gtk-doc-manual.xml:1568(function)
+msgid "xxx_get_type()"
+msgstr "xxx_get_type()"
+
+#: C/gtk-doc-manual.xml:1569(filename)
+msgid "<package>.types"
+msgstr "<package>.types"
+
+#: C/gtk-doc-manual.xml:1567(seg)
+msgid "The objects  function has not been entered into the  file."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1573(seg)
+msgid "Still no class hierarchy."
+msgstr "তথাপি ক্লাসের কোনো অনুক্রম নেই।"
+
+#: C/gtk-doc-manual.xml:1575(filename) C/gtk-doc-manual.xml:1614(filename) C/gtk-doc-manual.xml:1622(filename) C/gtk-doc-manual.xml:1644(filename)
+msgid "<package>-sections.txt"
+msgstr "<package>-sections.txt"
+
+#: C/gtk-doc-manual.xml:1576(ulink)
+msgid "explanation"
+msgstr "বর্ণনা"
+
+#: C/gtk-doc-manual.xml:1574(seg)
+msgid "Missing or wrong naming in  file (see )."
+msgstr " ফাইলের মধ্যে নাম অনুপস্থিত অথবা ভুল ( দেখুন)।"
+
+#: C/gtk-doc-manual.xml:1580(seg)
+msgid "Damn, I have still no class hierarchy."
+msgstr "এখনো কোনো ক্লাস অনুক্রম নেই।"
+
+#: C/gtk-doc-manual.xml:1582(type) C/gtk-doc-manual.xml:1623(type)
+msgid "GtkWidget"
+msgstr "GtkWidget"
+
+#: C/gtk-doc-manual.xml:1581(seg)
+msgid "Is the object name (name of the instance struct, e.g. ) part of the normal section (don't put this into Standard or Private subsections)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1588(seg)
+msgid "No symbol index."
+msgstr "সংকেতের ইন্ডেক্স অনুপস্থিত।"
+
+#: C/gtk-doc-manual.xml:1590(filename) C/gtk-doc-manual.xml:1605(filename) C/gtk-doc-manual.xml:1631(filename)
+msgid "<package>-docs.{xml,sgml}"
+msgstr "<package>-docs.{xml,sgml}"
+
+#: C/gtk-doc-manual.xml:1589(seg)
+msgid "Does the  contain a index that xi:includes the generated index?"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1595(seg)
+msgid "Symbols are not linked to their doc-section."
+msgstr "সিম্বলগুলি doc-section-র সাথে যুক্ত নয়।"
+
+#: C/gtk-doc-manual.xml:1596(seg)
+msgid "Is the doc-comment using the correct markup (added #,% or ())? Check if the gtkdoc-fixxref warns about unresolvable xrefs."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1602(seg)
+msgid "A new class does not appear in the docs."
+msgstr "নথির মধ্যে নতুন শ্রেণী উপস্থিত নেই।"
+
+#: C/gtk-doc-manual.xml:1603(seg)
+msgid "Is the new page xi:included from ."
+msgstr "নতুন পৃষ্ঠাটি  থেকে xi:include করে নির্মিত হয়েছে কি।"
+
+#: C/gtk-doc-manual.xml:1609(seg)
+msgid "A new symbol does not appear in the docs."
+msgstr "নথির মধ্যে নতুন সিম্বল অন্তর্ভুক্ত নয়।"
+
+#: C/gtk-doc-manual.xml:1610(seg)
+msgid "Is the doc-comment properly formatted. Check for spelling mistakes in the begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable xrefs. Check if the symbol is correctly listed in the  in a public subsection."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1618(seg)
+msgid "A type is missing from the class hierarchy."
+msgstr "ক্লাস অনুক্রম থেকে টাইপ অনুপস্থিত।"
+
+#: C/gtk-doc-manual.xml:1620(filename)
+msgid "<package>.hierarchy"
+msgstr "<package>.hierarchy"
+
+#: C/gtk-doc-manual.xml:1621(filename)
+msgid "xml/tree_index.sgml"
+msgstr "xml/tree_index.sgml"
+
+#: C/gtk-doc-manual.xml:1619(seg)
+msgid "If the type is listed in  but not in  then double check that the type is correctly placed in the . If the type instance (e.g. ) is not listed or incidentialy makred private it will not be shown."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1628(seg)
+msgid "I get foldoc links for all gobject annotations."
+msgstr "সকল gobject অ্যানোটেশনের জন্য foldoc লিংক পাওয়া গিয়েছে।"
+
+#: C/gtk-doc-manual.xml:1630(filename)
+msgid "xml/annotation-glossary.xml"
+msgstr "xml/annotation-glossary.xml"
+
+#: C/gtk-doc-manual.xml:1629(seg)
+msgid "Check that  is xi:included from ."
+msgstr "-কে  থেকে xi:included করা হয়েছে কি না পরীক্ষা করুন।"
+
+#: C/gtk-doc-manual.xml:1637(seg)
+msgid "Parameter described in source code comment block but does not exist"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1638(seg)
+msgid "Check if the prototype in the header has different parameter names as in the source."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1643(seg)
+msgid "multiple \"IDs\" for constraint linkend: XYZ"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1644(seg)
+msgid "Symbol XYZ appears twice in  file."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:1647(seg)
+msgid "Element typename in namespace '' encountered in para, but no template matches."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:12(releaseinfo)
+msgid "Version 1.1, March 2000"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:16(year)
+msgid "2000"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:16(holder)
+msgid "Free Software Foundation, Inc."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:19(para)
+msgid "
    Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA02110-1301USA
     Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:28(title)
+msgid "GNU Free Documentation License"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:31(title)
+msgid "0. PREAMBLE"
+msgstr "0. PREAMBLE"
+
+#: C/gtk-doc-manual.xml:32(para)
+msgid "The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:43(para)
+msgid "This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:50(para)
+msgid "We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:62(title)
+msgid "1. APPLICABILITY AND DEFINITIONS"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:63(para)
+msgid "This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:72(para)
+msgid "A Modified Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:79(para)
+msgid "A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:94(para)
+msgid "The Invariant Sections are certain  Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:103(para)
+msgid "The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:111(para)
+msgid "A Transparent copy of the  Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not Transparent is called Opaque."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:128(para)
+msgid "Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:141(para)
+msgid "The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:153(title)
+msgid "2. VERBATIM COPYING"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:154(para)
+msgid "You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:169(para)
+msgid "You may also lend copies, under the same conditions stated above, and you may publicly display copies."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:176(title)
+msgid "3. COPYING IN QUANTITY"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:177(para)
+msgid "If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:195(para)
+msgid "If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:202(para)
+msgid "If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:222(para)
+msgid "It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:231(title)
+msgid "4. MODIFICATIONS"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:232(para)
+msgid "You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:248(title)
+msgid "A"
+msgstr "A"
+
+#: C/gtk-doc-manual.xml:249(para)
+msgid "Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:264(title)
+msgid "B"
+msgstr "B"
+
+#: C/gtk-doc-manual.xml:265(para)
+msgid "List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five)."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:279(title)
+msgid "C"
+msgstr "C"
+
+#: C/gtk-doc-manual.xml:280(para)
+msgid "State on the Title Page the name of the publisher of the Modified Version, as the publisher."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:291(title)
+msgid "D"
+msgstr "D"
+
+#: C/gtk-doc-manual.xml:292(para)
+msgid "Preserve all the copyright notices of the Document."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:301(title)
+msgid "E"
+msgstr "E"
+
+#: C/gtk-doc-manual.xml:302(para)
+msgid "Add an appropriate copyright notice for your modifications adjacent to the other copyright notices."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:311(title)
+msgid "F"
+msgstr "F"
+
+#: C/gtk-doc-manual.xml:312(para)
+msgid "Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:324(title)
+msgid "G"
+msgstr "G"
+
+#: C/gtk-doc-manual.xml:325(para)
+msgid "Preserve in that license notice the full lists of  Invariant Sections and required Cover Texts given in the Document's license notice."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:337(title)
+msgid "H"
+msgstr "H"
+
+#: C/gtk-doc-manual.xml:338(para)
+msgid "Include an unaltered copy of this License."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:346(title)
+msgid "I"
+msgstr "I"
+
+#: C/gtk-doc-manual.xml:347(para)
+msgid "Preserve the section entitled History, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:365(title)
+msgid "J"
+msgstr "J"
+
+#: C/gtk-doc-manual.xml:366(para)
+msgid "Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:383(title)
+msgid "K"
+msgstr "K"
+
+#: C/gtk-doc-manual.xml:384(para)
+msgid "In any section entitled Acknowledgements or Dedications, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:396(title)
+msgid "L"
+msgstr "L"
+
+#: C/gtk-doc-manual.xml:397(para)
+msgid "Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:409(title)
+msgid "M"
+msgstr "M"
+
+#: C/gtk-doc-manual.xml:410(para)
+msgid "Delete any section entitled Endorsements. Such a section may not be included in the Modified Version."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:421(title)
+msgid "N"
+msgstr "N"
+
+#: C/gtk-doc-manual.xml:422(para)
+msgid "Do not retitle any existing section as Endorsements or to conflict in title with any Invariant Section."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:432(para)
+msgid "If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:444(para)
+msgid "You may add a section entitled Endorsements, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:453(para)
+msgid "You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:470(para)
+msgid "The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version ."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:480(title)
+msgid "5. COMBINING DOCUMENTS"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:481(para)
+msgid "You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:492(para)
+msgid "The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:505(para)
+msgid "In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled History; likewise combine any sections entitled Acknowledgements, and any sections entitled Dedications. You must delete all sections entitled Endorsements."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:516(title)
+msgid "6. COLLECTIONS OF DOCUMENTS"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:517(para)
+msgid "You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:527(para)
+msgid "You may extract a single document from such a collection, and dispbibute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:537(title)
+msgid "7. AGGREGATION WITH INDEPENDENT WORKS"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:538(para)
+msgid "A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an aggregate, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:561(title)
+msgid "8. TRANSLATION"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:562(para)
+msgid "Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing  Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:580(title)
+msgid "9. TERMINATION"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:581(para)
+msgid "You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:594(title)
+msgid "10. FUTURE REVISIONS OF THIS LICENSE"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:595(para)
+msgid "The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:606(para)
+msgid "Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:621(title)
+msgid "Addendum"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:622(para)
+msgid "To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:"
+msgstr ""
+
+#: C/gtk-doc-manual.xml:629(para)
+msgid "Copyright YEAR YOUR NAME."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:632(para)
+msgid "Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:647(para)
+msgid "If you have no Invariant Sections, write with no Invariant Sections instead of saying which ones are invariant. If you have no Front-Cover Texts, write no Front-Cover Texts instead of Front-Cover Texts being LIST; likewise for Back-Cover Texts."
+msgstr ""
+
+#: C/gtk-doc-manual.xml:657(para)
+msgid "If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the  GNU General Public License, to permit their use in free software."
+msgstr ""
+
+#. Put one translator per line, in the form of NAME , YEAR1, YEAR2
+#: C/gtk-doc-manual.xml:0(None)
+msgid "translator-credits"
+msgstr "রুণা ভট্টাচার্য্য (runab@redhat.com)"
+
diff --git a/gtk-doc-for-gtk4/help/manual/cs/cs.po b/gtk-doc-for-gtk4/help/manual/cs/cs.po
new file mode 100644
index 0000000000..f7117948f7
--- /dev/null
+++ b/gtk-doc-for-gtk4/help/manual/cs/cs.po
@@ -0,0 +1,5657 @@
+# Czech translation of gtk-doc.
+# Copyright (C) 2009 gtk-doc's COPYRIGHT HOLDER
+# This file is distributed under the same license as the gtk-doc package.
+# Marek Černocký , 2009, 2015, 2016, 2017, 2018, 2020.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: gtk-doc master\n"
+"POT-Creation-Date: 2019-10-02 10:49+0000\n"
+"PO-Revision-Date: 2020-03-08 10:38+0100\n"
+"Last-Translator: Marek Černocký \n"
+"Language-Team: čeština \n"
+"Language: cs\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;\n"
+"X-Generator: Gtranslator 2.91.7\n"
+
+#. Put one translator per line, in the form NAME , YEAR1, YEAR2
+msgctxt "_"
+msgid "translator-credits"
+msgstr "Marek Černocký "
+
+#. (itstool) path: bookinfo/title
+#: C/index.docbook:12
+msgid "GTK-Doc Manual"
+msgstr "Příručka ke GTK-Doc"
+
+#. (itstool) path: bookinfo/edition
+#: C/index.docbook:13
+msgid "1.24.1"
+msgstr "1.24.1"
+
+#. (itstool) path: abstract/para
+#: C/index.docbook:14
+msgid "User manual for developers with instructions of GTK-Doc usage."
+msgstr "Uživatelská příručka pro vývojáře s instrukcemi k používání GTK-Doc."
+
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:16
+msgid ""
+"Chris Lyttle  "
+"
     chris@wilddev.net 
         "
+msgstr ""
+"Chris Lyttle "
+"
    chris@wilddev.net
    "
+
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:25
+msgid ""
+"Dan Mueth  
     "
+"d-mueth@uchicago.edu 
         "
+msgstr ""
+"Dan Mueth "
+"
    d-mueth@uchicago.edu
    "
+
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:34
+msgid ""
+"Stefan Sauer (Kost)  "
+"
     ensonic@users.sf.net 
         "
+msgstr ""
+"Stefan Sauer (Kost) "
+"
    ensonic@users.sf.net
    "
+
+#. (itstool) path: publisher/publishername
+#: C/index.docbook:45
+msgid "GTK-Doc project"
+msgstr "Projekt GTK-Doc"
+
+#. (itstool) path: bookinfo/publisher
+#: C/index.docbook:44
+msgid ""
+"<_:publishername-1/> 
    gtk-doc-list@gnome.org
    "
+msgstr ""
+"<_:publishername-1/> 
    gtk-doc-list@gnome.org
    "
+
+#. (itstool) path: bookinfo/copyright
+#: C/index.docbook:48
+msgid "2000, 2005 Dan Mueth and Chris Lyttle"
+msgstr "2000, 2005 Dan Mueth and Chris Lyttle"
+
+#. (itstool) path: bookinfo/copyright
+#: C/index.docbook:52
+msgid "2007-2019 Stefan Sauer (Kost)"
+msgstr "2007-2019 Stefan Sauer (Kost)"
+
+#. (itstool) path: legalnotice/para
+#: C/index.docbook:65
+msgid ""
+"Permission is granted to copy, distribute and/or modify this document under "
+"the terms of the GNU Free Documentation License, "
+"Version 1.1 or any later version published by the Free Software Foundation "
+"with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A "
+"copy of the license is included."
+msgstr ""
+"Je povoleno kopírovat, šířit a/nebo upravovat tento dokument za podmínek "
+"GNU Free Documentation License ve verzi 1.1 nebo v "
+"jakékoli další verzi vydané nadací Free Software Foundation, s neměnnými "
+"oddíly, bez textů předních desek a bez textů zadních desek. Kopie licence je "
+"součástí."
+
+#. (itstool) path: legalnotice/para
+#: C/index.docbook:73
+msgid ""
+"Many of the names used by companies to distinguish their products and "
+"services are claimed as trademarks. Where those names appear in any GNOME "
+"documentation, and those trademarks are made aware to the members of the "
+"GNOME Documentation Project, the names have been printed in caps or initial "
+"caps."
+msgstr ""
+"Mnoho názvů použitých firmami k zviditelnění produktů nebo služeb jsou "
+"ochranné známky. Na místech, kde jsou tyto názvy v dokumentaci použity a "
+"členové Dokumentačního projektu GNOME jsou si vědomi skutečnosti, že se "
+"jedná o ochrannou známku, je takovýto název psán velkými písmeny celý nebo s "
+"velkým písmenem na začátku."
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:83
+msgid ""
+"1.32.1 15 Aug 2019 ss dev version"
+msgstr ""
+"1.32.1 15. srpna 2019 "
+"ss vývojová verze"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:89
+msgid ""
+"1.32 15 Aug 2019 ss hotfix release"
+msgstr ""
+"1.32 15. srpna 2019 ss opravné vydání"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
+"1.31 05 Aug 2019 ss refactorings and more test coverage"
+msgstr ""
+"1.31 5. srpna 2019 ss přepracování a větší pokrytí testy"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:101
+msgid ""
+"1.30 08 May 2019 ss more test coverage"
+msgstr ""
+"1.30 8. května 2019 ss větší pokrytí testy"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:107
+msgid ""
+"1.29 28 Aug 2018 ss bug fixes"
+msgstr ""
+"1.29 28. srpna 2018 ss opravy chyb"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:113
+msgid ""
+"1.28 24 Mar 2018 ss bug fixes"
+msgstr ""
+"1.28 24. března 2018 ss opravy chyb"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:119
+msgid ""
+"1.27 07 Dec 2017 ss fine tuning of the python port"
+msgstr ""
+"1.27 7. prosince 2017 "
+"ss detailní vyladění portu v "
+"jazyce Python"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:125
+msgid ""
+"1.26 11 Aug 2017 ss port all tools from perl/bash to python"
+msgstr ""
+"1.26 11. srpen 2017 ss přenesení všech nástrojů z jazyků Perl/Bash do "
+"jazyka Python"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:131
+msgid ""
+"1.25 21 March 2016 ss bug fixes, test cleanups"
+msgstr ""
+"1.25 21. březen 2016 ss opravy chyb, pročištění testů"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:137
+msgid ""
+"1.24 29 May 2015 ss bug fix"
+msgstr ""
+"1.24 29. května 2015 ss oprava chyby"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:143
+msgid ""
+"1.23 17 May 2015 ss bug fix"
+msgstr ""
+"1.23 17. květen 2015 ss oprava chyby"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:149
+msgid ""
+"1.22 07 May 2015 ss bug fixes, dropping deprecated features"
+msgstr ""
+"1.22 07. květen 2015 ss opravy chyb, odstranění zastaralých věcí"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:155
+msgid ""
+"1.21 17 Jul 2014 ss bug fixes, dropping deprecated features"
+msgstr ""
+"1.21 17. červenec 2014 "
+"ss opravy chyb, odstranění "
+"zastaralých věcí"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:161
+msgid ""
+"1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements"
+msgstr ""
+"1.20 16. únor 2014 ss opravy chyb, podpora značkovacího jazyka, "
+"vylepšení stylů"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:167
+msgid ""
+"1.19 05 Jun 2013 ss bug fixes"
+msgstr ""
+"1.19 05. červen 2013 ss opravy chyb"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:173
+msgid ""
+"1.18 14 Sep 2011 ss bug fixes, speedups, markdown support"
+msgstr ""
+"1.18 14. září 2011 ss opravy chyb, zrychlení, podpora značkovacího "
+"jazyka"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:179
+msgid ""
+"1.17 26 Feb 2011 sk urgent bug fix update"
+msgstr ""
+"1.17 26. únor 2011 sk aktualizace kvůli neodkladné opravě chyby"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:185
+msgid ""
+"1.16 14 Jan 2011 sk bugfixes, layout improvements"
+msgstr ""
+"1.16 14. leden 2011 sk opravy chyb, vylepšení vzhledu"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:191
+msgid ""
+"1.15 21 May 2010 sk bug and regression fixes"
+msgstr ""
+"1.15 21. květen 2010 sk opravy chyb a regresí"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:197
+msgid ""
+"1.14 28 March 2010 sk bugfixes and performance improvements"
+msgstr ""
+"1.14 28. březen 2010 sk opravy chyb a vylepšení výkonu"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:203
+msgid ""
+"1.13 18 December 2009 "
+"sk broken tarball update"
+msgstr ""
+"1.13 18. prosinec 2009 "
+"sk aktualizace poškozeného "
+"balíčku"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:209
+msgid ""
+"1.12 18 December 2009 "
+"sk new tool features and "
+"bugfixes"
+msgstr ""
+"1.12 18. prosinec 2009 "
+"sk nové funkce nástroje a opravy "
+"chyb"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:215
+msgid ""
+"1.11 16 November 2008 "
+"mal GNOME doc-utils migration"
+msgstr ""
+"1.11 16. listopad 2008 "
+"mal přechod na doc-utils z "
+"GNOME"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:228
+msgid "Introduction"
+msgstr "Úvod"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:230
+msgid ""
+"This chapter introduces GTK-Doc and gives an overview of what it is and how "
+"it is used."
+msgstr ""
+"Tato kapitola je úvodem do GTK-Doc a podává přehled o tom, co to je a jak to "
+"použít."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:236
+msgid "What is GTK-Doc?"
+msgstr "Co je to GTK-Doc?"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:238
+msgid ""
+"GTK-Doc is used to document C code. It is typically used to document the "
+"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
+"also be used to document application code."
+msgstr ""
+"GTK-Doc se používá k dokumentaci kódu jazyka C. Typické použití je pro "
+"dokumentaci veřejného API knihoven, jako jsou knihovny GTK+ a GNOME. Lze jej "
+"ale použít i k dokumentaci aplikačního kódu."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:246
+msgid "How Does GTK-Doc Work?"
+msgstr "Jak GTK-Doc pracuje?"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:248
+msgid ""
+"GTK-Doc works by using documentation of functions placed inside the source "
+"files in specially-formatted comment blocks, or documentation added to the "
+"template files which GTK-Doc uses (though note that GTK-Doc will only "
+"document functions that are declared in header files; it won't produce "
+"output for static functions)."
+msgstr ""
+"GTK-Doc pracuje na základě dokumentace funkcí umístěné přímo v souborech se "
+"zdrojovým kódem ve speciálně formátovaných komentářových blocích, nebo "
+"dokumentace přidané do souborů šablon, které GTK-Doc používá (ačkoliv je "
+"nutno poznamenat, že GTK-Doc dokumentuje pouze funkce, které jsou "
+"deklarované v hlavičkových souborech; pro statické funkce žádný výstup "
+"nevytváří)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:255
+msgid ""
+"GTK-Doc consists of a number of python scripts, each performing a different "
+"step in the process."
+msgstr ""
+"GTK-Doc sestává z řady skriptů v jazyce Python, z nichž každý provádí jinou "
+"část procesu."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:260
+msgid "There are 5 main steps in the process:"
+msgstr "Celý proces se skládá z pěti hlavních kroků:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:267
+msgid ""
+"Writing the documentation. The author fills in the "
+"source files with the documentation for each function, macro, structs or "
+"unions, etc."
+msgstr ""
+"Psaní dokumentace. Autor doplní soubory se zdrojovým "
+"kódem s dokumentací pro každou funkci, makro, strukturu, výčet atd."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:276
+msgid ""
+"Gathering information about the code. "
+"gtkdoc-scan scans the header files of the code "
+"looking for declarations of functions, macros, enums, structs, and unions. "
+"It creates the file <module>-decl-list.txt "
+"containing a list of the declarations, placing them into sections according "
+"to which header file they are in. On the first run this file is copied to "
+"<module>-sections.txt. The author can rearrange "
+"the sections, and the order of the declarations within them, to produce the "
+"final desired order. The second file it generates is <"
+"module>-decl.txt. This file contains the full declarations "
+"found by the scanner. If for some reason one would like some symbols to show "
+"up in the docs, where the full declaration cannot be found by the scanner or "
+"the declaration should appear differently, one can place entities similar to "
+"the ones in <module>-decl.txt into <"
+"module>-overrides.txt."
+msgstr ""
+"Shromáždění informací o kódu. gtkdoc-scan projde hlavičkové soubory kódu a vyhledá při tom deklarace "
+"funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor "
+"<module>-decl-list.txt obsahující seznam "
+"deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze "
+"kterého pochází. Při prvním spuštění se tento soubor zkopíruje do "
+"<module>-sections.txt. Autor může změnit "
+"uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve "
+"výsledku. Druhý soubor, který se vytvoří, je <module>-decl."
+"txt. Tento soubor obsahuje úplné deklarace nalezené při "
+"procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout "
+"symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá "
+"jinak, můžete jej umístit podobně jako v <module>-decl.txt do <module>-overrides.txt."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:293
+msgid ""
+"gtkdoc-scangobj can also be used to dynamically "
+"query a library about any GObject subclasses it exports. It saves "
+"information about each object's position in the class hierarchy and about "
+"any GObject properties and signals it provides."
+msgstr ""
+"Dá se také použít gtkdoc-scanobj k dynamickým "
+"dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se "
+"uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a "
+"signálech objektu GObject, které poskytují."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:299
+msgid ""
+"gtkdoc-scanobj should not be used anymore. It was "
+"needed in the past when GObject was still GtkObject inside gtk+."
+msgstr ""
+"gtkdoc-scanobj by se ale již používat nemělo. "
+"Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:306
+msgid ""
+"Generating the XML and HTML/PDF. gtkdoc-"
+"mkdb turns the template files into XML files in the xml/ subdirectory. If the source code "
+"contains documentation on functions, using the special comment blocks, it "
+"gets merged in here. If there are no tmpl files used it only reads docs from "
+"sources and introspection data."
+msgstr ""
+"Generování XML a HTML/PDF. gtkdoc-mkdb přemění soubory šablon na soubory XML v podsložce xml/. Pokud zdrojový kód obsahuje dokumentaci "
+"funkcí za použití speciálních komentářových bloků, tak zde se sloučí. V "
+"případě, že není použitý žádný soubor šablon, načte se dokumentace pouze ze "
+"zdrojového kódu a introspektivních dat."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:315
+msgid ""
+"gtkdoc-mkhtml turns the XML files into HTML files "
+"in the html/ subdirectory. Likewise "
+"gtkdoc-mkpdf turns the XML files into a PDF "
+"document called <package>.pdf."
+msgstr ""
+"gtkdoc-mkhtml převádí soubory XML na soubory HTML "
+"v podsložce html/. Obdobně "
+"gtkdoc-mkpdf převádí soubory XML na dokument PDF "
+"nazvaný <balíček>.pdf."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:321
+msgid ""
+"Files in xml/ and html/ directories are always overwritten. One "
+"should never edit them directly."
+msgstr ""
+"Soubory ve složkách xml/ a "
+"html/ jsou vždy přepsány. Nikdy by "
+"neměly být upravovány přímo."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:329
+msgid ""
+"Fixing up cross-references between documents. After "
+"installing the HTML files, gtkdoc-fixxref can be "
+"run to fix up any cross-references between separate documents. For example, "
+"the GTK+ documentation contains many cross-references to types documented in "
+"the GLib manual. When creating the source tarball for distribution, "
+"gtkdoc-rebase turns all external links into web-"
+"links. When installing distributed (pregenerated) docs the same application "
+"will try to turn links back to local links (where those docs are installed)."
+msgstr ""
+"Opravy křížových odkazů mezi dokumenty. Po "
+"nainstalování souborů HTML můžete spustit gtkdoc-fixxref, aby se opravily křížové odkazy mezi samostanými dokumenty. "
+"Například dokumentace GTK+ obsahuje křížové odkazy na typy zdokumentované v "
+"příručce GLib. Když vytváříte zdrojový balíček pro distribuci, "
+"gtkdoc-rebase předělá všechny externí odkazy na "
+"webové odkazy. Když se distribuovaná (předgenerovaná) dokumentace instaluje, "
+"pokusí se tatáž aplikace předělat odkazy zpátky na místní odkazy (na "
+"dokumenty, které jsou nainstalované)."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:347
+msgid "Getting GTK-Doc"
+msgstr "Jak získat GTK-Doc?"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:350
+msgid "Requirements"
+msgstr "Požadavky"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:351
+msgid ""
+"python 2/3 - the main scripts are written in python."
+msgstr "Python 2/3 – hlavní skripty jsou v jazyce Python."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:354
+msgid ""
+"xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/"
+msgstr ""
+"xsltproc – procesor xslt z knihovny libxslt xmlsoft.org/XSLT/"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:358
+msgid ""
+"docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl"
+msgstr ""
+"docbook-xsl – stylopisy XSL pro docbook sourceforge.net/projects/docbook/files/docbook-xsl"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:362
+msgid ""
+"One of source-highlight, highlight "
+"or vim - optional - used for syntax highlighting of "
+"examples"
+msgstr ""
+"Něco z source-highlight, highlight "
+"nebo vim – (volitelné) používá se pro zvýraznění "
+"syntaxe u příkladů"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:370
+msgid "About GTK-Doc"
+msgstr "O aplikaci GTK-Doc"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:372
+msgid ""
+"Historically GTK-Doc was used to generate template files from the sources "
+"code. These template files could be used by developers to enter the API "
+"documentation. This approach was rather inconvenient because it required to "
+"keep the generated files under version control. Since GTK-Doc 1.9 it became "
+"possible to place all API information into source comments, which made the "
+"template support obsolete. In version 1.26 template support has been removed."
+msgstr ""
+"Historicky se GTK-Doc používalo ke generování šablonových souborů ze "
+"zdrojových kódů. Tyto šablonové soubory pak mohli vývojáři používat ke "
+"vkládání dokumentace k API. Tento postup byl dosti nepohodlný, protože "
+"vyžadovat udržování vygenerovaných souborů ve správě verzí. Proto od verze "
+"1.9 přichází GTK-Doc s možností vkládat všechny informace o API do komentářů "
+"ve zdrojových kódech, čímž se podpora šablon stává nadbytečnou. Ve verzi "
+"1.26 byla podpora šablon odstraněna."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:382 C/index.docbook:396
+msgid "(FIXME)"
+msgstr "(DOPLNIT)"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:386
+msgid ""
+"(authors, web pages, mailing list, license, future plans, comparison with "
+"other similar systems.)"
+msgstr ""
+"(autoři, webové stránky, poštovní konference, licence, plány do budoucna, "
+"srovnání s ostatními podobnými systémy.)"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:394
+msgid "About this Manual"
+msgstr "O této příručce"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:400
+msgid "(who it is meant for, where you can get it, license)"
+msgstr "(k čemu je určená, kde ji můžete získat, licence)"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:409
+msgid "Project Setup"
+msgstr "Nastavení projektu"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:411
+msgid ""
+"This Chapter describes the steps that are necessary to integrate GTK-Doc "
+"into your project. The integration of GTK-Doc into a project includes the "
+"following steps:"
+msgstr ""
+"Tato kapitola popisuje kroky, které jsou nutné pro integraci GTK-Doc do "
+"vašeho projektu. Integrace GTK-Doc do projektu zahrnuje následující kroky:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:419
+msgid ""
+"Preparation of the directory structure and creating required configuration "
+"files for your GTK-Doc documentation (see  Setting up a skeleton documentation)."
+msgstr ""
+"Přípravu struktury složek a vytvoření požadovaných konfiguračních souborů "
+"pro dokumentaci GTK-Doc (viz Nastavení "
+"kostry dokumentace)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:427
+msgid ""
+"Adjusting the build system to build your documentation using the GTK-Doc "
+"tools. Multiple build systems are supported, in this manual we describe how "
+"to integrate GTK-Doc with Autotools, CMake, and plain Makefiles."
+msgstr ""
+"Přizpůsobení sestavovacího systému, aby sestavoval vaši dokumentaci pomocí "
+"nástrojů GTK-Doc. Je podporováno více sestavovacích systémů, v této příručce "
+"je popsáno, jak integrovat GTK-Doc s Autotools, CMake a prostými soubory Makefiles."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:437
+msgid ""
+"Adding GTK-Doc specific files to version control and deciding which files to "
+"ignore (see  Integration with version "
+"control systems)."
+msgstr ""
+"Přidání souborů specifických pro GTK-Doc do správy verzí a rozhodnutí, které "
+"soubory se mají ignorovat (viz Integrace se "
+"systémem správy verzí)."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:445
+msgid ""
+"The following sections assume we work on a project called meep. "
+"This project contains two packages (or modules), a library called "
+"libmeep and an end-user app called meeper."
+msgstr ""
+"Následující oddíly předpokládají, že pracujeme na projektu nazvaném "
+"meep. Tento projekt obsahuje dva balíčky (nebo moduly), "
+"knihovnu nazvanou libmeep a uživatelskou aplikaci nazvanou "
+"meeper."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:454
+msgid "Setting up a skeleton documentation"
+msgstr "Nastavení kostry dokumentace"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:456
+msgid ""
+"A common convention is to place documentation into a folder called "
+"docs inside your top-level project directory. We usually "
+"distinguish between reference documentation intended "
+"for developers and an user manual intended for end-"
+"users. Again the convention is to have separate folders for both. We usually "
+"place the reference documentation in a folder named reference "
+"and the end-user manual in a folder named help as. According to "
+"the above convention the documentation for our libmeep package "
+"would be placed into: docs/reference/libmeep. For packages with "
+"just one library or application the documentation could also be placed "
+"directly into docs/reference. It is not mandatory to use the "
+"above convention, but if you choose to use a different directory structure "
+"you must adjust your build system configuration to match your directory "
+"structure."
+msgstr ""
+"Zaběhnutým zvykem je umístit dokumentaci do složky nazvané docs "
+"ve složce nejvyšší úrovně projektu. Obvykle rozlišujeme mezi "
+"referenční dokumentací zaměřenou na vývojáře a "
+"uživatelskou příručkou zaměřenou na koncového "
+"uživatele. Opět je zvykem mít zvláštní složku pro každou z obou zmíněných. "
+"Obvykle umisťujeme referenční dokumentaci do složky nazvané reference a uživatelskou příručku do složky nazvané help. V souladu "
+"se zmíněnými zvyky by dokumentace pro naši knihovnu libmeep "
+"byla umístěna do docs/reference/libmeep. U balíčků s jedinou "
+"knihovnou nebo referenční dokumentací by bylo možné ji umístit přímo do "
+"docs/reference. Není povinné použít uvedenou konvenci, ale "
+"pokud se rozhodnete použít jinou strukturu složek, musíte upravit "
+"konfiguraci sestavovacího systému, aby se s ní shodoval."
+
+#. (itstool) path: example/title
+#: C/index.docbook:487
+msgid "Example directory structure of meep project"
+msgstr "Příklad struktury složek projektu meep"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:489
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+"  docs/\n"
+"    reference/  # reference documentation\n"
+"      libmeep/\n"
+"      meeper/\n"
+"    help/       # optional: user manual\n"
+"      meeper/\n"
+"  src/\n"
+"    libmeep/\n"
+"    meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+"  docs/\n"
+"    reference/  # referenční dokumentace\n"
+"      libmeep/\n"
+"      meeper/\n"
+"    help/       # volitelné: uživatelská příručka\n"
+"      meeper/\n"
+"  src/\n"
+"    libmeep/\n"
+"    meeper/\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:481
+msgid ""
+"In the following sections we will assume a directory structure for our "
+"meep project that uses the above conventions. <_:"
+"example-1/>"
+msgstr ""
+"V následujících oddílech budeme uvažovat strukturu složek pro náš projekt "
+"meep, který používá výše uvedené konvence. <_:example-1/"
+">"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:506
+msgid "Integration with Autotools"
+msgstr "Integrace s Autotools"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:507
+msgid ""
+"Integration of GTK-Doc into an autotools-based build system requires the "
+"following steps:"
+msgstr ""
+"Integrace GTK-Doc do sestavovacího systému založeného na Autotools vyžaduje "
+"následující kroky:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:513
+msgid ""
+"Ensure that gtkdocize is run once before the "
+"configure script. If an autogen.sh "
+"script is present, adjust it to check for GTK-Doc and add a call to "
+"gtkdocize."
+msgstr ""
+"Zajistit, že gtkdocize se spustí právě jednou "
+"před skriptem configure. Pokud je přítomen skript "
+"autogen.sh, upravte jej, aby kontroloval GTK-Doc a "
+"přidejte volání gtkdocize."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:521
+msgid ""
+"The main purpose of gtkdocize is to make the "
+"gtk-doc.make Makefile and the gtk-doc.m4 macro definition file available to the build system, either by "
+"copying or linking it into the project."
+msgstr ""
+"Hlavním účelem gtkdocize je vytvořit Makefile "
+"gtk-doc.make a definici makra gtk-doc.m4 dostupnou sestavovacímu systému, buď zkopírováním do projektu nebo "
+"vytvořením odkazu."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:530
+msgid ""
+"Add the necessary autoconf macros to "
+"configure.ac to enable GTK-Doc in your build system to "
+"allow configuration of GTK-Doc via the generated configure script."
+msgstr ""
+"Přidat potřebná makra autoconf do "
+"configure.ac, abyste povolili GTK-Doc v sestavovacím "
+"systému a konfigurace GTK-Doc mohla jít přes generovaný skript "
+"configure."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:536
+msgid ""
+"Among others with registers the --enable-gtk-doc option with "
+"the configure script."
+msgstr ""
+"Mimo jiné pomocí registrace přepínače --enable-gtk-doc ve "
+"skriptu configure."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:542
+msgid ""
+"Create an automake script for each application or "
+"library in your project. In the example used in this documentation this step "
+"applies to both meeper and libmeep."
+msgstr ""
+"Vytvořit skript automake pro jednotlivé aplikace "
+"a knihovny ve svém projektu. V příkladu použitém v této dokumentaci je tento "
+"krok použit jak pro meeper, tak pro libmeep."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:551
+msgid ""
+"In the following sections, we will perform the above steps in reverse order. "
+"We start with the automake scripts and work our "
+"way up to configure.ac and autogen.sh. Then we show how enable Gtk-Doc in the build system and how to "
+"build the documentation."
+msgstr ""
+"V následujícím oddíle provedeme výše zmíněné kroky v opačném pořadí. Začneme "
+"se skripty automake a budeme postupovat až k "
+"configure.ac a autogen.sh. Pak si "
+"ukážeme, jak povolit GTK-Doc v sestavovacím systému a jak sestavit "
+"dokumentaci."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:561
+msgid "Integration with automake"
+msgstr "Integrace s automake"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:563
+msgid ""
+"First copy the Makefile.am from the examples sub-directory of the  gtkdoc-"
+"sources to your project's reference documentation directory (e.g. "
+"docs/reference/<package>). A "
+"local copy should be available under e.g. /usr/share/doc/gtk-doc-"
+"tools/examples/Makefile.am. If you have multiple packages repeat "
+"this for each one."
+msgstr ""
+"Jako první nakopírujte Makefile.am z podsložky "
+"examples ve složce gtkdoc-sources do složky s referenční dokumentací svého projektu "
+"(např. ./docs/reference/<package>). Místní kopie by měla být k dispozici např. pod /usr/"
+"share/doc/gtk-doc-tools/examples/Makefile.am. Pokud máte více "
+"balíčků s dokumentací, opakujte tento krok pro každý z nich."
+
+#. (itstool) path: note/simpara
+#: C/index.docbook:576
+msgid ""
+"Do not forget to add each Makefile.am to the "
+"AC_CONFIG_FILES macro in configure.ac. For docs/reference/libmeep/Makefile.am you "
+"will need to add the entry docs/reference/libmeep/Makefile to AC_CONFIG_FILES."
+msgstr ""
+"Nezapomeňte přidat jednotlivé Makefile.am do makra "
+"AC_CONFIG_FILES v configure.ac. "
+"Pro docs/reference/libmeep/Makefile.am budete "
+"potřebovat přidat záznam docs/reference/libmeep/Makefile do AC_CONFIG_FILES."
+
+#. (itstool) path: example/title
+#: C/index.docbook:588
+msgid "Example directory structure with Makefiles.am"
+msgstr "Příklad struktury složek s Makefiles.am"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:591
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+"  docs/\n"
+"    reference/  # reference documentation\n"
+"      libmeep/\n"
+"        Makefile.am\n"
+"      meeper/\n"
+"        Makefile.am\n"
+"    help/       # optional: user manual\n"
+"      meeper/\n"
+"  src/\n"
+"    libmeep/\n"
+"    meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+"  docs/\n"
+"    reference/  # referenční dokumentace\n"
+"      libmeep/\n"
+"        Makefile.am\n"
+"      meeper/\n"
+"        Makefile.am\n"
+"    help/       # volitelné: uživatelská příručka\n"
+"      meeper/\n"
+"  src/\n"
+"    libmeep/\n"
+"    meeper/\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:607
+msgid ""
+"Next, you need to customize the copied Makefiles and provide values for the "
+"various parameters in each Makefile.am. All settings "
+"have a comment above them that describes their purpose and how to customize "
+"the setting. Most settings are used to supply extra flags to the respective "
+"tools to which they apply. Every tool has a variable of the form  (e.g. the tool gtkdoc-mkhtml has an option named MKHTML_OPTIONS). All the tools "
+"support  to list the supported options."
+msgstr ""
+"Dále je třeba přizpůsobit zkopírované soubory Makefile a dodat hodnoty pro "
+"různé parametry v jednotlivých Makefile.am. Všechna "
+"nastavení mají komentáře s popisem svého účelu a jak nastavení přizpůsobit. "
+"Většina nastavení má doplňující příznaky předávané do dotyčných nástrojů, "
+"které je umí použít. Každý nástroj má proměnnou ve formátu  (např. nástroj gtkdoc-"
+"mkhtml má volbu nazvanou MKHTML_OPTIONS). Všechny "
+"nástroje podporují  pro vypsání podporovaných "
+"přepínačů."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:631
+msgid ""
+" is used to provide the name of the package that "
+"is being documentated (e.g. meeper, or libmeep)."
+msgstr ""
+" se používá k poskytnutí názvu balíčku, který je "
+"dokumentován (např. meeper nebo libmeep)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:638
+msgid ""
+" is used to specify the location of source "
+"directory which GTK-Doc searches for your API documentation. This will "
+"usually be  DOC_SOURCE_DIR=$(top_srcdir)/src  or a sub-"
+"directory of that directory."
+msgstr ""
+" se používá k určení umístění zdrojové "
+"složky, ve které GTK-Doc hledá dokumentaci API. Obvykle to je "
+"DOC_SOURCE_DIR=$(top_srcdir)/src  nebo podsložka této složky."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:651
+msgid ""
+" and  are used for "
+"dependencies. Each option take a file-glob (e.g. HFILE_GLOB="
+"$(top_srcdir)/src/*.c). The documentation will be rebuilt if any of "
+"the matched files change."
+msgstr ""
+" a  se používají pro "
+"závislosti. Obě volby přebírají file-glob (např. HFILE_GLOB="
+"$(top_srcdir)/src/*.c). Dokumentace se znovu sestaví, když se "
+"kterýkoliv z odpovídajících souborů změní."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:663
+msgid ""
+" allows to specify extra header files to "
+"include when scanning for API documentation, which are not found under "
+"DOC_SOURCE_DIR (e.g.  EXTRA_HFILES=$(top_srcdir}/contrib/"
+"extra.h)."
+msgstr ""
+" umožňuje určit dodatečné hlavičkové soubory, "
+"které se mají zahrnout při procházení pro dokumentaci k API, a které nejsou "
+"k nalezení pod složkou DOC_SOURCE_DIR (např. EXTRA_HFILES="
+"$(top_srcdir}/contrib/extra.h)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:673
+msgid ""
+" allows to specify header files or directories "
+"to ignore when scanning for API documentation. Use the basename of the file "
+"or directory (e.g.  IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder)."
+msgstr ""
+" umožňuje určit dodatečné hlavičkové soubory "
+"nebo složky, které se mají ignorovat při procházení pro dokumentaci k API. "
+"Použijte základní název ze souboru nebo složky (např. "
+"IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:683
+msgid ""
+" allows to specify images files which will be "
+"copied into the html/ directory of the generated "
+"documentation. If your API documentation includes any images they need to be "
+"added to this option (e.g.  HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png)."
+msgstr ""
+" umožňuje určit soubory s obrázky, které se "
+"zkopírují do složky  s generovanou dokumentací. Pokud "
+"jsou součástí vaší dokumentace API nějaké obrázky, je třeba je přidat do "
+"této volby (např. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:696
+msgid ""
+" allows to specify extra files that are "
+"included by $(DOC_MAIN_SGML_FILE) (e.g.  "
+"content_files=running.xml building.xml changes-2.0.xml)."
+msgstr ""
+" umožňuje určit dodatečné soubory, které se "
+"mají vložit pomocí $(DOC_MAIN_SGML_FILE) (např. "
+"content_files=running.xml building.xml changes-2.0.xml)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:707
+msgid ""
+" allows to specify files where "
+"gtk-doc abbreviations such as #GtkWidget "
+"are expanded (e.g.  expand_content_files=running.xml)."
+msgstr ""
+" umožňuje určit soubory, ve kterých "
+"jsou rozvinuty zkratky gtk-doc, jako je třeba "
+"#GtkWidget (např. expand_content_files=running.xml)."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:625
+msgid ""
+"The following list explains the most relevant options. Check the example "
+"Makefile.am for additional options. <_:itemizedlist-1/>"
+msgstr ""
+"Následující seznam vysvětluje nejpodstatnější volby. Na další volby se "
+"podívejte do ukázkového Makefile.am. <_:itemizedlist-1/>"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:722
+msgid "Integration with autoconf"
+msgstr "Integrace s autoconf"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:724
+msgid ""
+"Integration with autoconf is very simple and "
+"includes one required step and an additional optional (but recommended) "
+"step. The first step is to add the GTK_DOC_CHECK macro "
+"to your configure.ac script. This registers several "
+"configure options to enable GTK-Doc and allows you to set default arguments "
+"for gtkdocize."
+msgstr ""
+"Integrace s autoconf je velmi jednoduchá a skládá "
+"se z jednoho povinného kroku a dalšího volitelného (ale doporučeného) kroku. "
+"Prvním krokem je přidat makro GTK_DOC_CHECK do skriptu "
+"configure.ac. Tím se zaregistruje několik "
+"konfiguračních voleb, které povolí GTK-Doc a umožní vám nastavit výchozí "
+"argumenty pro gtkdocize."
+
+#. (itstool) path: warning/simpara
+#: C/index.docbook:736
+msgid ""
+"Make sure that the GTK_DOC_CHECK macro is not indented. The "
+"macro must start at the beginning of the line and should not start with "
+"whitespace."
+msgstr ""
+"Ujistěte se, že makro GTK_DOC_CHECK není odsazené od kraje. "
+"Makro musí začínat na začátku řádku a nesmí začínat bílými znaky."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:743
+msgid ""
+"The second step is to add the AC_CONFIG_MACRO_DIR(m4) to your "
+"configure.ac. This is not required but helps "
+"gtkdocize to automatically copy the macro "
+"definition (e.g gtk-doc.m4) which contains the "
+"GTK_DOC_CHECK macro to your project's macro directory. "
+"Without this, the GTK_DOC_CHECK macro might not be found and you would need "
+"to explicitly tell the aclocal tool where to find "
+"the macro definition file."
+msgstr ""
+"Druhým krokem je přidat do configure.ac makro "
+"AC_CONFIG_MACRO_DIR(m4). Není to sice nutné, ale pomůže to "
+"gtkdocize automaticky zkopírovat definici makra "
+"(např. gtk-doc.m4), která obsahuje makro "
+"GTK_DOC_CHECK, do složky s makry ve vašem projektu. Bez "
+"toho se může stát, že makro GTK_DOC_CHECK nemusí být "
+"nalezeno a budete muset nástroji aclocal výslovně "
+"uvést, kde soubor s definicí makra najít."
+
+#. (itstool) path: example/title
+#: C/index.docbook:756
+msgid "Minimal integration with autoconf"
+msgstr "Minimální integrace s autoconf"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:757
+#, no-wrap
+msgid ""
+"\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
+msgstr ""
+"\n"
+"# doporučeno: nastaví složku m4\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# volitelné: zaregistruje gtk-doc v configure\n"
+"GTK_DOC_CHECK([1.28])\n"
+
+#. (itstool) path: example/title
+#: C/index.docbook:772
+msgid "Integration with optional gtk-doc dependency"
+msgstr "Integrace s volitelnými závislostttmi gtk-doc"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:773
+#, no-wrap
+msgid ""
+"\n"
+"m4_ifdef([GTK_DOC_CHECK], [\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
+"],[\n"
+"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
+"])\n"
+msgstr ""
+"\n"
+"m4_ifdef([GTK_DOC_CHECK], [\n"
+"# doporučeno: nastaví složku m4\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# volitelné: zaregistruje gtk-doc v configure\n"
+"GTK_DOC_CHECK([1.28])\n"
+"],[\n"
+"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
+"])\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:766
+msgid ""
+"The above example works, but will require all developers to have gtk-doc "
+"installed. A better way is to make building the documentation optional as "
+"shown in the next example: <_:example-1/>"
+msgstr ""
+"Výše uvedený příklad funguje, ale vyžaduje, aby všichni vývojáři měli "
+"nainstalováno gtk-doc. Lepším způsobem je zařídit, aby sestavení dokumentace "
+"bylo volitelné, jak je ukázáno v následujícím příkladu: <_:example-1/>"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:786
+msgid ""
+"The first argument is used to check for the Gtk-Doc version at configure "
+"time. The 2nd, optional argument is used by gtkdocize. The GTK_DOC_CHECK macro also adds several "
+"configure switches:"
+msgstr ""
+"První argument se používá ke kontrole verze GTK-Doc v průběhu konfigurace. "
+"Druhý, volitelný argument používá nástroj gtkdocize. Makro GTK_DOC_CHECK také přidává několik "
+"přepínačů pro configure:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:795
+msgid "--with-html-dir=PATH : path to installed docs"
+msgstr "--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:796
+msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
+msgstr ""
+"--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:797
+msgid ""
+"--enable-gtk-doc-html : build documentation in html format [default=yes]"
+msgstr ""
+"--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:798
+msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
+msgstr ""
+"--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]"
+
+#. (itstool) path: important/para
+#: C/index.docbook:802
+msgid ""
+"GTK-Doc is disabled by default! Remember to pass the option  to the next configure run. "
+"Otherwise pregenerated documentation is installed (which makes sense for "
+"users but not for developers)."
+msgstr ""
+"GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „“ při dalším spuštění configure. Jinak "
+"se nainstaluje předgenerovaná dokumentace (která může mít význam pro "
+"uživatele, ale ne pro vývojáře)."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:810
+msgid ""
+"After all changes to configure.ac are made, update the "
+"configure file. This can be done by re-running "
+"autogen.sh."
+msgstr ""
+"Po provedení změn v configure.ac aktualizujte soubor "
+"configure. To se dá udělat opětovným spuštěním "
+"autogen.sh."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:818
+msgid "Integration with autogen"
+msgstr "Integrace s autogen"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:820
+msgid ""
+"Most projects will have an autogen.sh script to setup "
+"the build infrastructure after the project was checked out from a version "
+"control system (such as git or svn). GTK-Doc comes with a script called "
+"gtkdocize which can be used to copy the necessary "
+"files needed by Gtk-Doc to the source directory."
+msgstr ""
+"Většina projektů má skript autogen.sh, který po stažení "
+"projektu ze systému pro správu verzí (jako je Git nebo SVN), nastaví "
+"infrastrukturu pro sestavení. GTK-Doc se dodává se skriptem nazvaným "
+"gtkdocize, který lze použít ke zkopírování "
+"nezbytných souborů požadovaných GTK-Doc do zdrojové složky."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:828
+msgid "It should be run before autoreconf, autoheader, automake or autoconf."
+msgstr "Měl by být spuštěn před autoheader, automake nebo autoconf."
+
+#. (itstool) path: example/title
+#: C/index.docbook:833
+msgid "Running gtkdocize from autogen.sh"
+msgstr "Spuštění gtkdocize z autogen.sh"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:834
+#, no-wrap
+msgid ""
+"\n"
+"gtkdocize || exit 1\n"
+msgstr ""
+"\n"
+"gtkdocize || exit 1\n"
+
+#. (itstool) path: example/title
+#: C/index.docbook:842
+msgid "Conditionally run gtkdocize from autogen.sh"
+msgstr "Podmíněné spuštění gtkdocize z autogen.sh"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:843
+#, no-wrap
+msgid ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+"  echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+"  $GTKDOCIZE || exit 1\n"
+"fi\n"
+msgstr ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+"  echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+"  $GTKDOCIZE || exit 1\n"
+"fi\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:854
+msgid ""
+"When running gtkdocize it copies gtk-"
+"doc.make to your project root (or any directory specified by the "
+" option)."
+msgstr ""
+"Když spustíte gtkdocize, tak nakopíruje do kořenové "
+"složky vašeho projektu (nebo složky určené přepínačem